0000: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a /***************
0010: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0020: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0030: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0040: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a ***************.
0050: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 69 73 20 ** This file is
0060: 61 6e 20 61 6d 61 6c 67 61 6d 61 74 69 6f 6e 20 an amalgamation
0070: 6f 66 20 6d 61 6e 79 20 73 65 70 61 72 61 74 65 of many separate
0080: 20 43 20 73 6f 75 72 63 65 20 66 69 6c 65 73 20 C source files
0090: 66 72 6f 6d 20 53 51 4c 69 74 65 0a 2a 2a 20 76 from SQLite.** v
00a0: 65 72 73 69 6f 6e 20 33 2e 31 32 2e 32 2e 20 20 ersion 3.12.2.
00b0: 42 79 20 63 6f 6d 62 69 6e 69 6e 67 20 61 6c 6c By combining all
00c0: 20 74 68 65 20 69 6e 64 69 76 69 64 75 61 6c 20 the individual
00d0: 43 20 63 6f 64 65 20 66 69 6c 65 73 20 69 6e 74 C code files int
00e0: 6f 20 74 68 69 73 20 0a 2a 2a 20 73 69 6e 67 6c o this .** singl
00f0: 65 20 6c 61 72 67 65 20 66 69 6c 65 2c 20 74 68 e large file, th
0100: 65 20 65 6e 74 69 72 65 20 63 6f 64 65 20 63 61 e entire code ca
0110: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 61 73 n be compiled as
0120: 20 61 20 73 69 6e 67 6c 65 20 74 72 61 6e 73 6c a single transl
0130: 61 74 69 6f 6e 0a 2a 2a 20 75 6e 69 74 2e 20 20 ation.** unit.
0140: 54 68 69 73 20 61 6c 6c 6f 77 73 20 6d 61 6e 79 This allows many
0150: 20 63 6f 6d 70 69 6c 65 72 73 20 74 6f 20 64 6f compilers to do
0160: 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 74 optimizations t
0170: 68 61 74 20 77 6f 75 6c 64 20 6e 6f 74 20 62 65 hat would not be
0180: 0a 2a 2a 20 70 6f 73 73 69 62 6c 65 20 69 66 20 .** possible if
0190: 74 68 65 20 66 69 6c 65 73 20 77 65 72 65 20 63 the files were c
01a0: 6f 6d 70 69 6c 65 64 20 73 65 70 61 72 61 74 65 ompiled separate
01b0: 6c 79 2e 20 20 50 65 72 66 6f 72 6d 61 6e 63 65 ly. Performance
01c0: 20 69 6d 70 72 6f 76 65 6d 65 6e 74 73 0a 2a 2a improvements.**
01d0: 20 6f 66 20 35 25 20 6f 72 20 6d 6f 72 65 20 61 of 5% or more a
01e0: 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 73 65 65 6e re commonly seen
01f0: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 when SQLite is
0200: 63 6f 6d 70 69 6c 65 64 20 61 73 20 61 20 73 69 compiled as a si
0210: 6e 67 6c 65 0a 2a 2a 20 74 72 61 6e 73 6c 61 74 ngle.** translat
0220: 69 6f 6e 20 75 6e 69 74 2e 0a 2a 2a 0a 2a 2a 20 ion unit..**.**
0230: 54 68 69 73 20 66 69 6c 65 20 69 73 20 61 6c 6c This file is all
0240: 20 79 6f 75 20 6e 65 65 64 20 74 6f 20 63 6f 6d you need to com
0250: 70 69 6c 65 20 53 51 4c 69 74 65 2e 20 20 54 6f pile SQLite. To
0260: 20 75 73 65 20 53 51 4c 69 74 65 20 69 6e 20 6f use SQLite in o
0270: 74 68 65 72 0a 2a 2a 20 70 72 6f 67 72 61 6d 73 ther.** programs
0280: 2c 20 79 6f 75 20 6e 65 65 64 20 74 68 69 73 20 , you need this
0290: 66 69 6c 65 20 61 6e 64 20 74 68 65 20 22 73 71 file and the "sq
02a0: 6c 69 74 65 33 2e 68 22 20 68 65 61 64 65 72 20 lite3.h" header
02b0: 66 69 6c 65 20 74 68 61 74 20 64 65 66 69 6e 65 file that define
02c0: 73 0a 2a 2a 20 74 68 65 20 70 72 6f 67 72 61 6d s.** the program
02d0: 6d 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 74 ming interface t
02e0: 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 o the SQLite lib
02f0: 72 61 72 79 2e 20 20 28 49 66 20 79 6f 75 20 64 rary. (If you d
0300: 6f 20 6e 6f 74 20 68 61 76 65 20 0a 2a 2a 20 74 o not have .** t
0310: 68 65 20 22 73 71 6c 69 74 65 33 2e 68 22 20 68 he "sqlite3.h" h
0320: 65 61 64 65 72 20 66 69 6c 65 20 61 74 20 68 61 eader file at ha
0330: 6e 64 2c 20 79 6f 75 20 77 69 6c 6c 20 66 69 6e nd, you will fin
0340: 64 20 61 20 63 6f 70 79 20 65 6d 62 65 64 64 65 d a copy embedde
0350: 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 d within.** the
0360: 74 65 78 74 20 6f 66 20 74 68 69 73 20 66 69 6c text of this fil
0370: 65 2e 20 20 53 65 61 72 63 68 20 66 6f 72 20 22 e. Search for "
0380: 42 65 67 69 6e 20 66 69 6c 65 20 73 71 6c 69 74 Begin file sqlit
0390: 65 33 2e 68 22 20 74 6f 20 66 69 6e 64 20 74 68 e3.h" to find th
03a0: 65 20 73 74 61 72 74 0a 2a 2a 20 6f 66 20 74 68 e start.** of th
03b0: 65 20 65 6d 62 65 64 64 65 64 20 73 71 6c 69 74 e embedded sqlit
03c0: 65 33 2e 68 20 68 65 61 64 65 72 20 66 69 6c 65 e3.h header file
03d0: 2e 29 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 6f .) Additional co
03e0: 64 65 20 66 69 6c 65 73 20 6d 61 79 20 62 65 20 de files may be
03f0: 6e 65 65 64 65 64 0a 2a 2a 20 69 66 20 79 6f 75 needed.** if you
0400: 20 77 61 6e 74 20 61 20 77 72 61 70 70 65 72 20 want a wrapper
0410: 74 6f 20 69 6e 74 65 72 66 61 63 65 20 53 51 4c to interface SQL
0420: 69 74 65 20 77 69 74 68 20 79 6f 75 72 20 63 68 ite with your ch
0430: 6f 69 63 65 20 6f 66 20 70 72 6f 67 72 61 6d 6d oice of programm
0440: 69 6e 67 0a 2a 2a 20 6c 61 6e 67 75 61 67 65 2e ing.** language.
0450: 20 54 68 65 20 63 6f 64 65 20 66 6f 72 20 74 68 The code for th
0460: 65 20 22 73 71 6c 69 74 65 33 22 20 63 6f 6d 6d e "sqlite3" comm
0470: 61 6e 64 2d 6c 69 6e 65 20 73 68 65 6c 6c 20 69 and-line shell i
0480: 73 20 61 6c 73 6f 20 69 6e 20 61 0a 2a 2a 20 73 s also in a.** s
0490: 65 70 61 72 61 74 65 20 66 69 6c 65 2e 20 54 68 eparate file. Th
04a0: 69 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73 is file contains
04b0: 20 6f 6e 6c 79 20 63 6f 64 65 20 66 6f 72 20 74 only code for t
04c0: 68 65 20 63 6f 72 65 20 53 51 4c 69 74 65 20 6c he core SQLite l
04d0: 69 62 72 61 72 79 2e 0a 2a 2f 0a 23 64 65 66 69 ibrary..*/.#defi
04e0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 45 20 31 ne SQLITE_CORE 1
04f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
0500: 41 4d 41 4c 47 41 4d 41 54 49 4f 4e 20 31 0a 23 AMALGAMATION 1.#
0510: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 50 52 ifndef SQLITE_PR
0520: 49 56 41 54 45 0a 23 20 64 65 66 69 6e 65 20 53 IVATE.# define S
0530: 51 4c 49 54 45 5f 50 52 49 56 41 54 45 20 73 74 QLITE_PRIVATE st
0540: 61 74 69 63 0a 23 65 6e 64 69 66 0a 2f 2a 2a 2a atic.#endif./***
0550: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 *********** Begi
0560: 6e 20 66 69 6c 65 20 73 71 6c 69 74 65 49 6e 74 n file sqliteInt
0570: 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a .h *************
0580: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0590: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a **********/./*.*
05a0: 2a 20 32 30 30 31 20 53 65 70 74 65 6d 62 65 72 * 2001 September
05b0: 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 15.**.** The au
05c0: 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63 thor disclaims c
05d0: 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73 opyright to this
05e0: 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49 source code. I
05f0: 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 n place of.** a
0600: 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 legal notice, he
0610: 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67 re is a blessing
0620: 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 :.**.** May y
0630: 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e ou do good and n
0640: 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d ot evil..** M
0650: 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 ay you find forg
0660: 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 iveness for your
0670: 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65 self and forgive
0680: 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d others..** M
0690: 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65 ay you share fre
06a0: 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e ely, never takin
06b0: 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 g more than you
06c0: 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a give..**.*******
06d0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
06e0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
06f0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0700: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0710: 2a 2a 0a 2a 2a 20 49 6e 74 65 72 6e 61 6c 20 69 **.** Internal i
0720: 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 69 74 nterface definit
0730: 69 6f 6e 73 20 66 6f 72 20 53 51 4c 69 74 65 2e ions for SQLite.
0740: 0a 2a 2a 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f .**.*/.#ifndef _
0750: 53 51 4c 49 54 45 49 4e 54 5f 48 5f 0a 23 64 65 SQLITEINT_H_.#de
0760: 66 69 6e 65 20 5f 53 51 4c 49 54 45 49 4e 54 5f fine _SQLITEINT_
0770: 48 5f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73 H_../*.** Make s
0780: 75 72 65 20 74 68 61 74 20 72 61 6e 64 5f 73 28 ure that rand_s(
0790: 29 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 6f ) is available o
07a0: 6e 20 57 69 6e 64 6f 77 73 20 73 79 73 74 65 6d n Windows system
07b0: 73 20 77 69 74 68 20 4d 53 56 43 20 32 30 30 35 s with MSVC 2005
07c0: 0a 2a 2a 20 6f 72 20 68 69 67 68 65 72 2e 0a 2a .** or higher..*
07d0: 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28 5f 4d /.#if defined(_M
07e0: 53 43 5f 56 45 52 29 20 26 26 20 5f 4d 53 43 5f SC_VER) && _MSC_
07f0: 56 45 52 3e 3d 31 34 30 30 0a 23 20 20 64 65 66 VER>=1400.# def
0800: 69 6e 65 20 5f 43 52 54 5f 52 41 4e 44 5f 53 0a ine _CRT_RAND_S.
0810: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 49 6e #endif../*.** In
0820: 63 6c 75 64 65 20 74 68 65 20 68 65 61 64 65 72 clude the header
0830: 20 66 69 6c 65 20 75 73 65 64 20 74 6f 20 63 75 file used to cu
0840: 73 74 6f 6d 69 7a 65 20 74 68 65 20 63 6f 6d 70 stomize the comp
0850: 69 6c 65 72 20 6f 70 74 69 6f 6e 73 20 66 6f 72 iler options for
0860: 20 4d 53 56 43 2e 0a 2a 2a 20 54 68 69 73 20 73 MSVC..** This s
0870: 68 6f 75 6c 64 20 62 65 20 64 6f 6e 65 20 66 69 hould be done fi
0880: 72 73 74 20 73 6f 20 74 68 61 74 20 69 74 20 63 rst so that it c
0890: 61 6e 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 an successfully
08a0: 70 72 65 76 65 6e 74 20 73 70 75 72 69 6f 75 73 prevent spurious
08b0: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 77 61 72 .** compiler war
08c0: 6e 69 6e 67 73 20 64 75 65 20 74 6f 20 73 75 62 nings due to sub
08d0: 73 65 71 75 65 6e 74 20 63 6f 6e 74 65 6e 74 20 sequent content
08e0: 69 6e 20 74 68 69 73 20 66 69 6c 65 20 61 6e 64 in this file and
08f0: 20 6f 74 68 65 72 20 66 69 6c 65 73 0a 2a 2a 20 other files.**
0900: 74 68 61 74 20 61 72 65 20 69 6e 63 6c 75 64 65 that are include
0910: 64 20 62 79 20 74 68 69 73 20 66 69 6c 65 2e 0a d by this file..
0920: 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a */./************
0930: 2a 2a 20 49 6e 63 6c 75 64 65 20 6d 73 76 63 2e ** Include msvc.
0940: 68 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 h in the middle
0950: 6f 66 20 73 71 6c 69 74 65 49 6e 74 2e 68 20 2a of sqliteInt.h *
0960: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0970: 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a */./************
0980: 2a 2a 20 42 65 67 69 6e 20 66 69 6c 65 20 6d 73 ** Begin file ms
0990: 76 63 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a vc.h ***********
09a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
09b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
09c0: 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30 31 35 20 4a 61 */./*.** 2015 Ja
09d0: 6e 75 61 72 79 20 31 32 0a 2a 2a 0a 2a 2a 20 54 nuary 12.**.** T
09e0: 68 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 he author discla
09f0: 69 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f ims copyright to
0a00: 20 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 this source cod
0a10: 65 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a e. In place of.
0a20: 2a 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 ** a legal notic
0a30: 65 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 e, here is a ble
0a40: 73 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 ssing:.**.**
0a50: 4d 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 May you do good
0a60: 61 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a and not evil..**
0a70: 20 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 May you find
0a80: 20 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 forgiveness for
0a90: 20 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f yourself and fo
0aa0: 72 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a rgive others..**
0ab0: 20 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 May you shar
0ac0: 65 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 e freely, never
0ad0: 74 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e taking more than
0ae0: 20 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a you give..**.**
0af0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0b00: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0b10: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0b20: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0b30: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a ************.**.
0b40: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e ** This file con
0b50: 74 61 69 6e 73 20 63 6f 64 65 20 74 68 61 74 20 tains code that
0b60: 69 73 20 73 70 65 63 69 66 69 63 20 74 6f 20 4d is specific to M
0b70: 53 56 43 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 SVC..*/.#ifndef
0b80: 5f 4d 53 56 43 5f 48 5f 0a 23 64 65 66 69 6e 65 _MSVC_H_.#define
0b90: 20 5f 4d 53 56 43 5f 48 5f 0a 0a 23 69 66 20 64 _MSVC_H_..#if d
0ba0: 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 efined(_MSC_VER)
0bb0: 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67 .#pragma warning
0bc0: 28 64 69 73 61 62 6c 65 20 3a 20 34 30 35 34 29 (disable : 4054)
0bd0: 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67 .#pragma warning
0be0: 28 64 69 73 61 62 6c 65 20 3a 20 34 30 35 35 29 (disable : 4055)
0bf0: 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67 .#pragma warning
0c00: 28 64 69 73 61 62 6c 65 20 3a 20 34 31 30 30 29 (disable : 4100)
0c10: 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67 .#pragma warning
0c20: 28 64 69 73 61 62 6c 65 20 3a 20 34 31 32 37 29 (disable : 4127)
0c30: 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67 .#pragma warning
0c40: 28 64 69 73 61 62 6c 65 20 3a 20 34 31 33 30 29 (disable : 4130)
0c50: 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67 .#pragma warning
0c60: 28 64 69 73 61 62 6c 65 20 3a 20 34 31 35 32 29 (disable : 4152)
0c70: 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67 .#pragma warning
0c80: 28 64 69 73 61 62 6c 65 20 3a 20 34 31 38 39 29 (disable : 4189)
0c90: 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67 .#pragma warning
0ca0: 28 64 69 73 61 62 6c 65 20 3a 20 34 32 30 36 29 (disable : 4206)
0cb0: 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67 .#pragma warning
0cc0: 28 64 69 73 61 62 6c 65 20 3a 20 34 32 31 30 29 (disable : 4210)
0cd0: 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67 .#pragma warning
0ce0: 28 64 69 73 61 62 6c 65 20 3a 20 34 32 33 32 29 (disable : 4232)
0cf0: 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67 .#pragma warning
0d00: 28 64 69 73 61 62 6c 65 20 3a 20 34 32 34 34 29 (disable : 4244)
0d10: 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67 .#pragma warning
0d20: 28 64 69 73 61 62 6c 65 20 3a 20 34 33 30 35 29 (disable : 4305)
0d30: 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67 .#pragma warning
0d40: 28 64 69 73 61 62 6c 65 20 3a 20 34 33 30 36 29 (disable : 4306)
0d50: 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67 .#pragma warning
0d60: 28 64 69 73 61 62 6c 65 20 3a 20 34 37 30 32 29 (disable : 4702)
0d70: 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67 .#pragma warning
0d80: 28 64 69 73 61 62 6c 65 20 3a 20 34 37 30 36 29 (disable : 4706)
0d90: 0a 23 65 6e 64 69 66 20 2f 2a 20 64 65 66 69 6e .#endif /* defin
0da0: 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 2a 2f 0a ed(_MSC_VER) */.
0db0: 0a 23 65 6e 64 69 66 20 2f 2a 20 5f 4d 53 56 43 .#endif /* _MSVC
0dc0: 5f 48 5f 20 2a 2f 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a _H_ */../*******
0dd0: 2a 2a 2a 2a 2a 2a 2a 20 45 6e 64 20 6f 66 20 6d ******* End of m
0de0: 73 76 63 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a svc.h **********
0df0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0e00: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0e10: 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a ******/./*******
0e20: 2a 2a 2a 2a 2a 2a 2a 20 43 6f 6e 74 69 6e 75 69 ******* Continui
0e30: 6e 67 20 77 68 65 72 65 20 77 65 20 6c 65 66 74 ng where we left
0e40: 20 6f 66 66 20 69 6e 20 73 71 6c 69 74 65 49 6e off in sqliteIn
0e50: 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a t.h ************
0e60: 2a 2a 2a 2a 2a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 ******/../*.** S
0e70: 70 65 63 69 61 6c 20 73 65 74 75 70 20 66 6f 72 pecial setup for
0e80: 20 56 78 57 6f 72 6b 73 0a 2a 2f 0a 2f 2a 2a 2a VxWorks.*/./***
0e90: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 49 6e 63 6c *********** Incl
0ea0: 75 64 65 20 76 78 77 6f 72 6b 73 2e 68 20 69 6e ude vxworks.h in
0eb0: 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 73 the middle of s
0ec0: 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a qliteInt.h *****
0ed0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a **********/./***
0ee0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 *********** Begi
0ef0: 6e 20 66 69 6c 65 20 76 78 77 6f 72 6b 73 2e 68 n file vxworks.h
0f00: 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ***************
0f10: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0f20: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a **********/./*.*
0f30: 2a 20 32 30 31 35 2d 30 33 2d 30 32 0a 2a 2a 0a * 2015-03-02.**.
0f40: 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 20 64 69 ** The author di
0f50: 73 63 6c 61 69 6d 73 20 63 6f 70 79 72 69 67 68 sclaims copyrigh
0f60: 74 20 74 6f 20 74 68 69 73 20 73 6f 75 72 63 65 t to this source
0f70: 20 63 6f 64 65 2e 20 20 49 6e 20 70 6c 61 63 65 code. In place
0f80: 20 6f 66 0a 2a 2a 20 61 20 6c 65 67 61 6c 20 6e of.** a legal n
0f90: 6f 74 69 63 65 2c 20 68 65 72 65 20 69 73 20 61 otice, here is a
0fa0: 20 62 6c 65 73 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a blessing:.**.**
0fb0: 20 20 20 20 4d 61 79 20 79 6f 75 20 64 6f 20 67 May you do g
0fc0: 6f 6f 64 20 61 6e 64 20 6e 6f 74 20 65 76 69 6c ood and not evil
0fd0: 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 ..** May you
0fe0: 66 69 6e 64 20 66 6f 72 67 69 76 65 6e 65 73 73 find forgiveness
0ff0: 20 66 6f 72 20 79 6f 75 72 73 65 6c 66 20 61 6e for yourself an
1000: 64 20 66 6f 72 67 69 76 65 20 6f 74 68 65 72 73 d forgive others
1010: 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 ..** May you
1020: 73 68 61 72 65 20 66 72 65 65 6c 79 2c 20 6e 65 share freely, ne
1030: 76 65 72 20 74 61 6b 69 6e 67 20 6d 6f 72 65 20 ver taking more
1040: 74 68 61 6e 20 79 6f 75 20 67 69 76 65 2e 0a 2a than you give..*
1050: 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a *.**************
1060: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1070: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1080: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1090: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
10a0: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 .**.** This file
10b0: 20 63 6f 6e 74 61 69 6e 73 20 63 6f 64 65 20 74 contains code t
10c0: 68 61 74 20 69 73 20 73 70 65 63 69 66 69 63 20 hat is specific
10d0: 74 6f 20 57 69 6e 64 20 52 69 76 65 72 27 73 20 to Wind River's
10e0: 56 78 57 6f 72 6b 73 0a 2a 2f 0a 23 69 66 20 64 VxWorks.*/.#if d
10f0: 65 66 69 6e 65 64 28 5f 5f 52 54 50 5f 5f 29 20 efined(__RTP__)
1100: 7c 7c 20 64 65 66 69 6e 65 64 28 5f 57 52 53 5f || defined(_WRS_
1110: 4b 45 52 4e 45 4c 29 0a 2f 2a 20 54 68 69 73 20 KERNEL)./* This
1120: 69 73 20 56 78 57 6f 72 6b 73 2e 20 20 53 65 74 is VxWorks. Set
1130: 20 75 70 20 74 68 69 6e 67 73 20 73 70 65 63 69 up things speci
1140: 61 6c 6c 79 20 66 6f 72 20 74 68 61 74 20 4f 53 ally for that OS
1150: 0a 2a 2f 0a 23 69 6e 63 6c 75 64 65 20 3c 76 78 .*/.#include <vx
1160: 57 6f 72 6b 73 2e 68 3e 0a 23 69 6e 63 6c 75 64 Works.h>.#includ
1170: 65 20 3c 70 74 68 72 65 61 64 2e 68 3e 20 20 2f e <pthread.h> /
1180: 2a 20 61 6d 61 6c 67 61 6d 61 74 6f 72 3a 20 64 * amalgamator: d
1190: 6f 6e 74 63 61 63 68 65 20 2a 2f 0a 23 64 65 66 ontcache */.#def
11a0: 69 6e 65 20 4f 53 5f 56 58 57 4f 52 4b 53 20 31 ine OS_VXWORKS 1
11b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
11c0: 4f 53 5f 4f 54 48 45 52 20 30 0a 23 64 65 66 69 OS_OTHER 0.#defi
11d0: 6e 65 20 53 51 4c 49 54 45 5f 48 4f 4d 45 47 52 ne SQLITE_HOMEGR
11e0: 4f 57 4e 5f 52 45 43 55 52 53 49 56 45 5f 4d 55 OWN_RECURSIVE_MU
11f0: 54 45 58 20 31 0a 23 64 65 66 69 6e 65 20 53 51 TEX 1.#define SQ
1200: 4c 49 54 45 5f 4f 4d 49 54 5f 4c 4f 41 44 5f 45 LITE_OMIT_LOAD_E
1210: 58 54 45 4e 53 49 4f 4e 20 31 0a 23 64 65 66 69 XTENSION 1.#defi
1220: 6e 65 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 ne SQLITE_ENABLE
1230: 5f 4c 4f 43 4b 49 4e 47 5f 53 54 59 4c 45 20 30 _LOCKING_STYLE 0
1240: 0a 23 64 65 66 69 6e 65 20 48 41 56 45 5f 55 54 .#define HAVE_UT
1250: 49 4d 45 20 31 0a 23 65 6c 73 65 0a 2f 2a 20 54 IME 1.#else./* T
1260: 68 69 73 20 69 73 20 6e 6f 74 20 56 78 57 6f 72 his is not VxWor
1270: 6b 73 2e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 4f ks. */.#define O
1280: 53 5f 56 58 57 4f 52 4b 53 20 30 0a 23 64 65 66 S_VXWORKS 0.#def
1290: 69 6e 65 20 48 41 56 45 5f 46 43 48 4f 57 4e 20 ine HAVE_FCHOWN
12a0: 31 0a 23 64 65 66 69 6e 65 20 48 41 56 45 5f 52 1.#define HAVE_R
12b0: 45 41 44 4c 49 4e 4b 20 31 0a 23 64 65 66 69 6e EADLINK 1.#defin
12c0: 65 20 48 41 56 45 5f 4c 53 54 41 54 20 31 0a 23 e HAVE_LSTAT 1.#
12d0: 65 6e 64 69 66 20 2f 2a 20 64 65 66 69 6e 65 64 endif /* defined
12e0: 28 5f 57 52 53 5f 4b 45 52 4e 45 4c 29 20 2a 2f (_WRS_KERNEL) */
12f0: 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ../*************
1300: 2a 20 45 6e 64 20 6f 66 20 76 78 77 6f 72 6b 73 * End of vxworks
1310: 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a .h *************
1320: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1330: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1340: 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a /./*************
1350: 2a 20 43 6f 6e 74 69 6e 75 69 6e 67 20 77 68 65 * Continuing whe
1360: 72 65 20 77 65 20 6c 65 66 74 20 6f 66 66 20 69 re we left off i
1370: 6e 20 73 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a n sqliteInt.h **
1380: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1390: 2f 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 23 /../*.** These #
13a0: 64 65 66 69 6e 65 73 20 73 68 6f 75 6c 64 20 65 defines should e
13b0: 6e 61 62 6c 65 20 3e 32 47 42 20 66 69 6c 65 20 nable >2GB file
13c0: 73 75 70 70 6f 72 74 20 6f 6e 20 50 4f 53 49 58 support on POSIX
13d0: 20 69 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 if the.** under
13e0: 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 lying operating
13f0: 73 79 73 74 65 6d 20 73 75 70 70 6f 72 74 73 20 system supports
1400: 69 74 2e 20 20 49 66 20 74 68 65 20 4f 53 20 6c it. If the OS l
1410: 61 63 6b 73 0a 2a 2a 20 6c 61 72 67 65 20 66 69 acks.** large fi
1420: 6c 65 20 73 75 70 70 6f 72 74 2c 20 6f 72 20 69 le support, or i
1430: 66 20 74 68 65 20 4f 53 20 69 73 20 77 69 6e 64 f the OS is wind
1440: 6f 77 73 2c 20 74 68 65 73 65 20 73 68 6f 75 6c ows, these shoul
1450: 64 20 62 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a d be no-ops..**.
1460: 2a 2a 20 54 69 63 6b 65 74 20 23 32 37 33 39 3a ** Ticket #2739:
1470: 20 20 54 68 65 20 5f 4c 41 52 47 45 46 49 4c 45 The _LARGEFILE
1480: 5f 53 4f 55 52 43 45 20 6d 61 63 72 6f 20 6d 75 _SOURCE macro mu
1490: 73 74 20 61 70 70 65 61 72 20 62 65 66 6f 72 65 st appear before
14a0: 20 61 6e 79 0a 2a 2a 20 73 79 73 74 65 6d 20 23 any.** system #
14b0: 69 6e 63 6c 75 64 65 73 2e 20 20 48 65 6e 63 65 includes. Hence
14c0: 2c 20 74 68 69 73 20 62 6c 6f 63 6b 20 6f 66 20 , this block of
14d0: 63 6f 64 65 20 6d 75 73 74 20 62 65 20 74 68 65 code must be the
14e0: 20 76 65 72 79 20 66 69 72 73 74 0a 2a 2a 20 63 very first.** c
14f0: 6f 64 65 20 69 6e 20 61 6c 6c 20 73 6f 75 72 63 ode in all sourc
1500: 65 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 4c e files..**.** L
1510: 61 72 67 65 20 66 69 6c 65 20 73 75 70 70 6f 72 arge file suppor
1520: 74 20 63 61 6e 20 62 65 20 64 69 73 61 62 6c 65 t can be disable
1530: 64 20 75 73 69 6e 67 20 74 68 65 20 2d 44 53 51 d using the -DSQ
1540: 4c 49 54 45 5f 44 49 53 41 42 4c 45 5f 4c 46 53 LITE_DISABLE_LFS
1550: 20 73 77 69 74 63 68 0a 2a 2a 20 6f 6e 20 74 68 switch.** on th
1560: 65 20 63 6f 6d 70 69 6c 65 72 20 63 6f 6d 6d 61 e compiler comma
1570: 6e 64 20 6c 69 6e 65 2e 20 20 54 68 69 73 20 69 nd line. This i
1580: 73 20 6e 65 63 65 73 73 61 72 79 20 69 66 20 79 s necessary if y
1590: 6f 75 20 61 72 65 20 63 6f 6d 70 69 6c 69 6e 67 ou are compiling
15a0: 0a 2a 2a 20 6f 6e 20 61 20 72 65 63 65 6e 74 20 .** on a recent
15b0: 6d 61 63 68 69 6e 65 20 28 65 78 3a 20 52 65 64 machine (ex: Red
15c0: 20 48 61 74 20 37 2e 32 29 20 62 75 74 20 79 6f Hat 7.2) but yo
15d0: 75 20 77 61 6e 74 20 79 6f 75 72 20 63 6f 64 65 u want your code
15e0: 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 6f 6e 20 61 to work.** on a
15f0: 6e 20 6f 6c 64 65 72 20 6d 61 63 68 69 6e 65 20 n older machine
1600: 28 65 78 3a 20 52 65 64 20 48 61 74 20 36 2e 30 (ex: Red Hat 6.0
1610: 29 2e 20 20 49 66 20 79 6f 75 20 63 6f 6d 70 69 ). If you compi
1620: 6c 65 20 6f 6e 20 52 65 64 20 48 61 74 20 37 2e le on Red Hat 7.
1630: 32 0a 2a 2a 20 77 69 74 68 6f 75 74 20 74 68 69 2.** without thi
1640: 73 20 6f 70 74 69 6f 6e 2c 20 4c 46 53 20 69 73 s option, LFS is
1650: 20 65 6e 61 62 6c 65 2e 20 20 42 75 74 20 4c 46 enable. But LF
1660: 53 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 S does not exist
1670: 20 69 6e 20 74 68 65 20 6b 65 72 6e 65 6c 0a 2a in the kernel.*
1680: 2a 20 69 6e 20 52 65 64 20 48 61 74 20 36 2e 30 * in Red Hat 6.0
1690: 2c 20 73 6f 20 74 68 65 20 63 6f 64 65 20 77 6f , so the code wo
16a0: 6e 27 74 20 77 6f 72 6b 2e 20 20 48 65 6e 63 65 n't work. Hence
16b0: 2c 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 62 69 , for maximum bi
16c0: 6e 61 72 79 0a 2a 2a 20 70 6f 72 74 61 62 69 6c nary.** portabil
16d0: 69 74 79 20 79 6f 75 20 73 68 6f 75 6c 64 20 6f ity you should o
16e0: 6d 69 74 20 4c 46 53 2e 0a 2a 2a 0a 2a 2a 20 54 mit LFS..**.** T
16f0: 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 he previous para
1700: 67 72 61 70 68 20 77 61 73 20 77 72 69 74 74 65 graph was writte
1710: 6e 20 69 6e 20 32 30 30 35 2e 20 20 28 54 68 69 n in 2005. (Thi
1720: 73 20 70 61 72 61 67 72 61 70 68 20 69 73 20 77 s paragraph is w
1730: 72 69 74 74 65 6e 0a 2a 2a 20 6f 6e 20 32 30 30 ritten.** on 200
1740: 38 2d 31 31 2d 32 38 2e 29 20 54 68 65 73 65 20 8-11-28.) These
1750: 64 61 79 73 2c 20 61 6c 6c 20 4c 69 6e 75 78 20 days, all Linux
1760: 6b 65 72 6e 65 6c 73 20 73 75 70 70 6f 72 74 20 kernels support
1770: 6c 61 72 67 65 20 66 69 6c 65 73 2c 20 73 6f 0a large files, so.
1780: 2a 2a 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 ** you should pr
1790: 6f 62 61 62 6c 79 20 6c 65 61 76 65 20 4c 46 53 obably leave LFS
17a0: 20 65 6e 61 62 6c 65 64 2e 20 20 42 75 74 20 73 enabled. But s
17b0: 6f 6d 65 20 65 6d 62 65 64 64 65 64 20 70 6c 61 ome embedded pla
17c0: 74 66 6f 72 6d 73 20 6d 69 67 68 74 0a 2a 2a 20 tforms might.**
17d0: 6c 61 63 6b 20 4c 46 53 20 69 6e 20 77 68 69 63 lack LFS in whic
17e0: 68 20 63 61 73 65 20 74 68 65 20 53 51 4c 49 54 h case the SQLIT
17f0: 45 5f 44 49 53 41 42 4c 45 5f 4c 46 53 20 6d 61 E_DISABLE_LFS ma
1800: 63 72 6f 20 6d 69 67 68 74 20 73 74 69 6c 6c 20 cro might still
1810: 62 65 20 75 73 65 66 75 6c 2e 0a 2a 2a 0a 2a 2a be useful..**.**
1820: 20 53 69 6d 69 6c 61 72 20 69 73 20 74 72 75 65 Similar is true
1830: 20 66 6f 72 20 4d 61 63 20 4f 53 20 58 2e 20 20 for Mac OS X.
1840: 4c 46 53 20 69 73 20 6f 6e 6c 79 20 73 75 70 70 LFS is only supp
1850: 6f 72 74 65 64 20 6f 6e 20 4d 61 63 20 4f 53 20 orted on Mac OS
1860: 58 20 39 20 61 6e 64 20 6c 61 74 65 72 2e 0a 2a X 9 and later..*
1870: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 /.#ifndef SQLITE
1880: 5f 44 49 53 41 42 4c 45 5f 4c 46 53 0a 23 20 64 _DISABLE_LFS.# d
1890: 65 66 69 6e 65 20 5f 4c 41 52 47 45 5f 46 49 4c efine _LARGE_FIL
18a0: 45 20 20 20 20 20 20 20 31 0a 23 20 69 66 6e 64 E 1.# ifnd
18b0: 65 66 20 5f 46 49 4c 45 5f 4f 46 46 53 45 54 5f ef _FILE_OFFSET_
18c0: 42 49 54 53 0a 23 20 20 20 64 65 66 69 6e 65 20 BITS.# define
18d0: 5f 46 49 4c 45 5f 4f 46 46 53 45 54 5f 42 49 54 _FILE_OFFSET_BIT
18e0: 53 20 36 34 0a 23 20 65 6e 64 69 66 0a 23 20 64 S 64.# endif.# d
18f0: 65 66 69 6e 65 20 5f 4c 41 52 47 45 46 49 4c 45 efine _LARGEFILE
1900: 5f 53 4f 55 52 43 45 20 31 0a 23 65 6e 64 69 66 _SOURCE 1.#endif
1910: 0a 0a 2f 2a 20 57 68 61 74 20 76 65 72 73 69 6f ../* What versio
1920: 6e 20 6f 66 20 47 43 43 20 69 73 20 62 65 69 6e n of GCC is bein
1930: 67 20 75 73 65 64 2e 20 20 30 20 6d 65 61 6e 73 g used. 0 means
1940: 20 47 43 43 20 69 73 20 6e 6f 74 20 62 65 69 6e GCC is not bein
1950: 67 20 75 73 65 64 20 2a 2f 0a 23 69 66 64 65 66 g used */.#ifdef
1960: 20 5f 5f 47 4e 55 43 5f 5f 0a 23 20 64 65 66 69 __GNUC__.# defi
1970: 6e 65 20 47 43 43 5f 56 45 52 53 49 4f 4e 20 28 ne GCC_VERSION (
1980: 5f 5f 47 4e 55 43 5f 5f 2a 31 30 30 30 30 30 30 __GNUC__*1000000
1990: 2b 5f 5f 47 4e 55 43 5f 4d 49 4e 4f 52 5f 5f 2a +__GNUC_MINOR__*
19a0: 31 30 30 30 2b 5f 5f 47 4e 55 43 5f 50 41 54 43 1000+__GNUC_PATC
19b0: 48 4c 45 56 45 4c 5f 5f 29 0a 23 65 6c 73 65 0a HLEVEL__).#else.
19c0: 23 20 64 65 66 69 6e 65 20 47 43 43 5f 56 45 52 # define GCC_VER
19d0: 53 49 4f 4e 20 30 0a 23 65 6e 64 69 66 0a 0a 2f SION 0.#endif../
19e0: 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 76 61 72 * Needed for var
19f0: 69 6f 75 73 20 64 65 66 69 6e 69 74 69 6f 6e 73 ious definitions
1a00: 2e 2e 2e 20 2a 2f 0a 23 69 66 20 64 65 66 69 6e ... */.#if defin
1a10: 65 64 28 5f 5f 47 4e 55 43 5f 5f 29 20 26 26 20 ed(__GNUC__) &&
1a20: 21 64 65 66 69 6e 65 64 28 5f 47 4e 55 5f 53 4f !defined(_GNU_SO
1a30: 55 52 43 45 29 0a 23 20 64 65 66 69 6e 65 20 5f URCE).# define _
1a40: 47 4e 55 5f 53 4f 55 52 43 45 0a 23 65 6e 64 69 GNU_SOURCE.#endi
1a50: 66 0a 0a 23 69 66 20 64 65 66 69 6e 65 64 28 5f f..#if defined(_
1a60: 5f 4f 70 65 6e 42 53 44 5f 5f 29 20 26 26 20 21 _OpenBSD__) && !
1a70: 64 65 66 69 6e 65 64 28 5f 42 53 44 5f 53 4f 55 defined(_BSD_SOU
1a80: 52 43 45 29 0a 23 20 64 65 66 69 6e 65 20 5f 42 RCE).# define _B
1a90: 53 44 5f 53 4f 55 52 43 45 0a 23 65 6e 64 69 66 SD_SOURCE.#endif
1aa0: 0a 0a 2f 2a 0a 2a 2a 20 46 6f 72 20 4d 69 6e 47 ../*.** For MinG
1ab0: 57 2c 20 63 68 65 63 6b 20 74 6f 20 73 65 65 20 W, check to see
1ac0: 69 66 20 77 65 20 63 61 6e 20 69 6e 63 6c 75 64 if we can includ
1ad0: 65 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c e the header fil
1ae0: 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 74 73 e containing its
1af0: 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 69 6e 66 6f .** version info
1b00: 72 6d 61 74 69 6f 6e 2c 20 61 6d 6f 6e 67 20 6f rmation, among o
1b10: 74 68 65 72 20 74 68 69 6e 67 73 2e 20 20 4e 6f ther things. No
1b20: 72 6d 61 6c 6c 79 2c 20 74 68 69 73 20 69 6e 74 rmally, this int
1b30: 65 72 6e 61 6c 20 4d 69 6e 47 57 0a 2a 2a 20 68 ernal MinGW.** h
1b40: 65 61 64 65 72 20 66 69 6c 65 20 77 6f 75 6c 64 eader file would
1b50: 20 5b 6f 6e 6c 79 5d 20 62 65 20 69 6e 63 6c 75 [only] be inclu
1b60: 64 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c ded automaticall
1b70: 79 20 62 79 20 6f 74 68 65 72 20 4d 69 6e 47 57 y by other MinGW
1b80: 20 68 65 61 64 65 72 0a 2a 2a 20 66 69 6c 65 73 header.** files
1b90: 3b 20 68 6f 77 65 76 65 72 2c 20 74 68 65 20 63 ; however, the c
1ba0: 6f 6e 74 61 69 6e 65 64 20 76 65 72 73 69 6f 6e ontained version
1bb0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 information is
1bc0: 6e 6f 77 20 72 65 71 75 69 72 65 64 20 62 79 20 now required by
1bd0: 74 68 69 73 0a 2a 2a 20 68 65 61 64 65 72 20 66 this.** header f
1be0: 69 6c 65 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 ile to work arou
1bf0: 6e 64 20 62 69 6e 61 72 79 20 63 6f 6d 70 61 74 nd binary compat
1c00: 69 62 69 6c 69 74 79 20 69 73 73 75 65 73 20 28 ibility issues (
1c10: 73 65 65 20 62 65 6c 6f 77 29 20 61 6e 64 0a 2a see below) and.*
1c20: 2a 20 74 68 69 73 20 69 73 20 74 68 65 20 6f 6e * this is the on
1c30: 6c 79 20 6b 6e 6f 77 6e 20 77 61 79 20 74 6f 20 ly known way to
1c40: 72 65 6c 69 61 62 6c 79 20 6f 62 74 61 69 6e 20 reliably obtain
1c50: 69 74 2e 20 20 54 68 69 73 20 65 6e 74 69 72 65 it. This entire
1c60: 20 23 69 66 20 62 6c 6f 63 6b 0a 2a 2a 20 77 6f #if block.** wo
1c70: 75 6c 64 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c uld be completel
1c80: 79 20 75 6e 6e 65 63 65 73 73 61 72 79 20 69 66 y unnecessary if
1c90: 20 74 68 65 72 65 20 77 61 73 20 61 6e 79 20 6f there was any o
1ca0: 74 68 65 72 20 77 61 79 20 6f 66 20 64 65 74 65 ther way of dete
1cb0: 63 74 69 6e 67 0a 2a 2a 20 4d 69 6e 47 57 20 76 cting.** MinGW v
1cc0: 69 61 20 74 68 65 69 72 20 70 72 65 70 72 6f 63 ia their preproc
1cd0: 65 73 73 6f 72 20 28 65 2e 67 2e 20 69 66 20 74 essor (e.g. if t
1ce0: 68 65 79 20 63 75 73 74 6f 6d 69 7a 65 64 20 74 hey customized t
1cf0: 68 65 69 72 20 47 43 43 20 74 6f 20 64 65 66 69 heir GCC to defi
1d00: 6e 65 0a 2a 2a 20 73 6f 6d 65 20 4d 69 6e 47 57 ne.** some MinGW
1d10: 2d 73 70 65 63 69 66 69 63 20 6d 61 63 72 6f 73 -specific macros
1d20: 29 2e 20 20 57 68 65 6e 20 63 6f 6d 70 69 6c 69 ). When compili
1d30: 6e 67 20 66 6f 72 20 4d 69 6e 47 57 2c 20 65 69 ng for MinGW, ei
1d40: 74 68 65 72 20 74 68 65 0a 2a 2a 20 5f 48 41 56 ther the.** _HAV
1d50: 45 5f 4d 49 4e 47 57 5f 48 20 6f 72 20 5f 48 41 E_MINGW_H or _HA
1d60: 56 45 5f 5f 4d 49 4e 47 57 5f 48 20 28 6e 6f 74 VE__MINGW_H (not
1d70: 65 20 74 68 65 20 65 78 74 72 61 20 75 6e 64 65 e the extra unde
1d80: 72 73 63 6f 72 65 29 20 6d 61 63 72 6f 20 6d 75 rscore) macro mu
1d90: 73 74 20 62 65 0a 2a 2a 20 64 65 66 69 6e 65 64 st be.** defined
1da0: 3b 20 6f 74 68 65 72 77 69 73 65 2c 20 64 65 74 ; otherwise, det
1db0: 65 63 74 69 6f 6e 20 6f 66 20 63 6f 6e 64 69 74 ection of condit
1dc0: 69 6f 6e 73 20 73 70 65 63 69 66 69 63 20 74 6f ions specific to
1dd0: 20 4d 69 6e 47 57 20 77 69 6c 6c 20 62 65 0a 2a MinGW will be.*
1de0: 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2f 0a 23 * disabled..*/.#
1df0: 69 66 20 64 65 66 69 6e 65 64 28 5f 48 41 56 45 if defined(_HAVE
1e00: 5f 4d 49 4e 47 57 5f 48 29 0a 23 20 69 6e 63 6c _MINGW_H).# incl
1e10: 75 64 65 20 22 6d 69 6e 67 77 2e 68 22 0a 23 65 ude "mingw.h".#e
1e20: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 48 41 56 lif defined(_HAV
1e30: 45 5f 5f 4d 49 4e 47 57 5f 48 29 0a 23 20 69 6e E__MINGW_H).# in
1e40: 63 6c 75 64 65 20 22 5f 6d 69 6e 67 77 2e 68 22 clude "_mingw.h"
1e50: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 46 .#endif../*.** F
1e60: 6f 72 20 4d 69 6e 47 57 20 76 65 72 73 69 6f 6e or MinGW version
1e70: 20 34 2e 78 20 28 61 6e 64 20 68 69 67 68 65 72 4.x (and higher
1e80: 29 2c 20 63 68 65 63 6b 20 74 6f 20 73 65 65 20 ), check to see
1e90: 69 66 20 74 68 65 20 5f 55 53 45 5f 33 32 42 49 if the _USE_32BI
1ea0: 54 5f 54 49 4d 45 5f 54 0a 2a 2a 20 64 65 66 69 T_TIME_T.** defi
1eb0: 6e 65 20 69 73 20 72 65 71 75 69 72 65 64 20 74 ne is required t
1ec0: 6f 20 6d 61 69 6e 74 61 69 6e 20 62 69 6e 61 72 o maintain binar
1ed0: 79 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 y compatibility
1ee0: 77 69 74 68 20 74 68 65 20 4d 53 56 43 20 72 75 with the MSVC ru
1ef0: 6e 74 69 6d 65 0a 2a 2a 20 6c 69 62 72 61 72 79 ntime.** library
1f00: 20 69 6e 20 75 73 65 20 28 65 2e 67 2e 20 66 6f in use (e.g. fo
1f10: 72 20 57 69 6e 64 6f 77 73 20 58 50 29 2e 0a 2a r Windows XP)..*
1f20: 2f 0a 23 69 66 20 21 64 65 66 69 6e 65 64 28 5f /.#if !defined(_
1f30: 55 53 45 5f 33 32 42 49 54 5f 54 49 4d 45 5f 54 USE_32BIT_TIME_T
1f40: 29 20 26 26 20 21 64 65 66 69 6e 65 64 28 5f 55 ) && !defined(_U
1f50: 53 45 5f 36 34 42 49 54 5f 54 49 4d 45 5f 54 29 SE_64BIT_TIME_T)
1f60: 20 26 26 20 5c 0a 20 20 20 20 64 65 66 69 6e 65 && \. define
1f70: 64 28 5f 57 49 4e 33 32 29 20 26 26 20 21 64 65 d(_WIN32) && !de
1f80: 66 69 6e 65 64 28 5f 57 49 4e 36 34 29 20 26 26 fined(_WIN64) &&
1f90: 20 5c 0a 20 20 20 20 64 65 66 69 6e 65 64 28 5f \. defined(_
1fa0: 5f 4d 49 4e 47 57 5f 4d 41 4a 4f 52 5f 56 45 52 _MINGW_MAJOR_VER
1fb0: 53 49 4f 4e 29 20 26 26 20 5f 5f 4d 49 4e 47 57 SION) && __MINGW
1fc0: 5f 4d 41 4a 4f 52 5f 56 45 52 53 49 4f 4e 20 3e _MAJOR_VERSION >
1fd0: 3d 20 34 20 26 26 20 5c 0a 20 20 20 20 64 65 66 = 4 && \. def
1fe0: 69 6e 65 64 28 5f 5f 4d 53 56 43 52 54 5f 5f 29 ined(__MSVCRT__)
1ff0: 0a 23 20 64 65 66 69 6e 65 20 5f 55 53 45 5f 33 .# define _USE_3
2000: 32 42 49 54 5f 54 49 4d 45 5f 54 0a 23 65 6e 64 2BIT_TIME_T.#end
2010: 69 66 0a 0a 2f 2a 20 54 68 65 20 70 75 62 6c 69 if../* The publi
2020: 63 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 c SQLite interfa
2030: 63 65 2e 20 20 54 68 65 20 5f 46 49 4c 45 5f 4f ce. The _FILE_O
2040: 46 46 53 45 54 5f 42 49 54 53 20 6d 61 63 72 6f FFSET_BITS macro
2050: 20 6d 75 73 74 20 61 70 70 65 61 72 0a 2a 2a 20 must appear.**
2060: 66 69 72 73 74 20 69 6e 20 51 4e 58 2e 20 20 41 first in QNX. A
2070: 6c 73 6f 2c 20 74 68 65 20 5f 55 53 45 5f 33 32 lso, the _USE_32
2080: 42 49 54 5f 54 49 4d 45 5f 54 20 6d 61 63 72 6f BIT_TIME_T macro
2090: 20 6d 75 73 74 20 61 70 70 65 61 72 20 66 69 72 must appear fir
20a0: 73 74 20 66 6f 72 0a 2a 2a 20 4d 69 6e 47 57 2e st for.** MinGW.
20b0: 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a .*/./***********
20c0: 2a 2a 2a 20 49 6e 63 6c 75 64 65 20 73 71 6c 69 *** Include sqli
20d0: 74 65 33 2e 68 20 69 6e 20 74 68 65 20 6d 69 64 te3.h in the mid
20e0: 64 6c 65 20 6f 66 20 73 71 6c 69 74 65 49 6e 74 dle of sqliteInt
20f0: 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a .h *************
2100: 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a **/./***********
2110: 2a 2a 2a 20 42 65 67 69 6e 20 66 69 6c 65 20 73 *** Begin file s
2120: 71 6c 69 74 65 33 2e 68 20 2a 2a 2a 2a 2a 2a 2a qlite3.h *******
2130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
2140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
2150: 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 **/./*.** 2001 S
2160: 65 70 74 65 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a eptember 15.**.*
2170: 2a 20 54 68 65 20 61 75 74 68 6f 72 20 64 69 73 * The author dis
2180: 63 6c 61 69 6d 73 20 63 6f 70 79 72 69 67 68 74 claims copyright
2190: 20 74 6f 20 74 68 69 73 20 73 6f 75 72 63 65 20 to this source
21a0: 63 6f 64 65 2e 20 20 49 6e 20 70 6c 61 63 65 20 code. In place
21b0: 6f 66 0a 2a 2a 20 61 20 6c 65 67 61 6c 20 6e 6f of.** a legal no
21c0: 74 69 63 65 2c 20 68 65 72 65 20 69 73 20 61 20 tice, here is a
21d0: 62 6c 65 73 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 blessing:.**.**
21e0: 20 20 20 4d 61 79 20 79 6f 75 20 64 6f 20 67 6f May you do go
21f0: 6f 64 20 61 6e 64 20 6e 6f 74 20 65 76 69 6c 2e od and not evil.
2200: 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 66 .** May you f
2210: 69 6e 64 20 66 6f 72 67 69 76 65 6e 65 73 73 20 ind forgiveness
2220: 66 6f 72 20 79 6f 75 72 73 65 6c 66 20 61 6e 64 for yourself and
2230: 20 66 6f 72 67 69 76 65 20 6f 74 68 65 72 73 2e forgive others.
2240: 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 73 .** May you s
2250: 68 61 72 65 20 66 72 65 65 6c 79 2c 20 6e 65 76 hare freely, nev
2260: 65 72 20 74 61 6b 69 6e 67 20 6d 6f 72 65 20 74 er taking more t
2270: 68 61 6e 20 79 6f 75 20 67 69 76 65 2e 0a 2a 2a han you give..**
2280: 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a .***************
2290: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
22a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
22b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
22c0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 **********.** Th
22d0: 69 73 20 68 65 61 64 65 72 20 66 69 6c 65 20 64 is header file d
22e0: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 efines the inter
22f0: 66 61 63 65 20 74 68 61 74 20 74 68 65 20 53 51 face that the SQ
2300: 4c 69 74 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 Lite library.**
2310: 70 72 65 73 65 6e 74 73 20 74 6f 20 63 6c 69 65 presents to clie
2320: 6e 74 20 70 72 6f 67 72 61 6d 73 2e 20 20 49 66 nt programs. If
2330: 20 61 20 43 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 a C-function, s
2340: 74 72 75 63 74 75 72 65 2c 20 64 61 74 61 74 79 tructure, dataty
2350: 70 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 pe,.** or consta
2360: 6e 74 20 64 65 66 69 6e 69 74 69 6f 6e 20 64 6f nt definition do
2370: 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 69 6e es not appear in
2380: 20 74 68 69 73 20 66 69 6c 65 2c 20 74 68 65 6e this file, then
2390: 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 it is.** not a
23a0: 70 75 62 6c 69 73 68 65 64 20 41 50 49 20 6f 66 published API of
23b0: 20 53 51 4c 69 74 65 2c 20 69 73 20 73 75 62 6a SQLite, is subj
23c0: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69 ect to change wi
23d0: 74 68 6f 75 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c thout.** notice,
23e0: 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 and should not
23f0: 62 65 20 72 65 66 65 72 65 6e 63 65 64 20 62 79 be referenced by
2400: 20 70 72 6f 67 72 61 6d 73 20 74 68 61 74 20 75 programs that u
2410: 73 65 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a se SQLite..**.**
2420: 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 64 65 66 Some of the def
2430: 69 6e 69 74 69 6f 6e 73 20 74 68 61 74 20 61 72 initions that ar
2440: 65 20 69 6e 20 74 68 69 73 20 66 69 6c 65 20 61 e in this file a
2450: 72 65 20 6d 61 72 6b 65 64 20 61 73 0a 2a 2a 20 re marked as.**
2460: 22 65 78 70 65 72 69 6d 65 6e 74 61 6c 22 2e 20 "experimental".
2470: 20 45 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e Experimental in
2480: 74 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f 72 terfaces are nor
2490: 6d 61 6c 6c 79 20 6e 65 77 0a 2a 2a 20 66 65 61 mally new.** fea
24a0: 74 75 72 65 73 20 72 65 63 65 6e 74 6c 79 20 61 tures recently a
24b0: 64 64 65 64 20 74 6f 20 53 51 4c 69 74 65 2e 20 dded to SQLite.
24c0: 20 57 65 20 64 6f 20 6e 6f 74 20 61 6e 74 69 63 We do not antic
24d0: 69 70 61 74 65 20 63 68 61 6e 67 65 73 0a 2a 2a ipate changes.**
24e0: 20 74 6f 20 65 78 70 65 72 69 6d 65 6e 74 61 6c to experimental
24f0: 20 69 6e 74 65 72 66 61 63 65 73 20 62 75 74 20 interfaces but
2500: 72 65 73 65 72 76 65 20 74 68 65 20 72 69 67 68 reserve the righ
2510: 74 20 74 6f 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 t to make minor
2520: 63 68 61 6e 67 65 73 0a 2a 2a 20 69 66 20 65 78 changes.** if ex
2530: 70 65 72 69 65 6e 63 65 20 66 72 6f 6d 20 75 73 perience from us
2540: 65 20 22 69 6e 20 74 68 65 20 77 69 6c 64 22 20 e "in the wild"
2550: 73 75 67 67 65 73 74 20 73 75 63 68 20 63 68 61 suggest such cha
2560: 6e 67 65 73 20 61 72 65 20 70 72 75 64 65 6e 74 nges are prudent
2570: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 66 66 69 ..**.** The offi
2580: 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61 67 65 20 cial C-language
2590: 41 50 49 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f API documentatio
25a0: 6e 20 66 6f 72 20 53 51 4c 69 74 65 20 69 73 20 n for SQLite is
25b0: 64 65 72 69 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 derived.** from
25c0: 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74 68 69 73 comments in this
25d0: 20 66 69 6c 65 2e 20 20 54 68 69 73 20 66 69 6c file. This fil
25e0: 65 20 69 73 20 74 68 65 20 61 75 74 68 6f 72 69 e is the authori
25f0: 74 61 74 69 76 65 20 73 6f 75 72 63 65 0a 2a 2a tative source.**
2600: 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74 65 20 69 on how SQLite i
2610: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 73 75 nterfaces are su
2620: 70 70 6f 73 65 64 20 74 6f 20 6f 70 65 72 61 74 pposed to operat
2630: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d e..**.** The nam
2640: 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20 75 e of this file u
2650: 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 nder configurati
2660: 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 69 73 on management is
2670: 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a "sqlite.h.in"..
2680: 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c 65 20 ** The makefile
2690: 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 makes some minor
26a0: 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 69 73 changes to this
26b0: 20 66 69 6c 65 20 28 73 75 63 68 20 61 73 20 69 file (such as i
26c0: 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68 65 20 nserting.** the
26d0: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 29 20 version number)
26e0: 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74 73 20 and changes its
26f0: 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74 65 33 name to "sqlite3
2700: 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f .h" as.** part o
2710: 66 20 74 68 65 20 62 75 69 6c 64 20 70 72 6f 63 f the build proc
2720: 65 73 73 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 ess..*/.#ifndef
2730: 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23 64 65 66 _SQLITE3_H_.#def
2740: 69 6e 65 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a ine _SQLITE3_H_.
2750: 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72 67 #include <stdarg
2760: 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64 65 .h> /* Neede
2770: 64 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e 69 d for the defini
2780: 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74 20 tion of va_list
2790: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73 */../*.** Make s
27a0: 75 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c 20 ure we can call
27b0: 74 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d 20 this stuff from
27c0: 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 20 30 0a 65 78 C++..*/.#if 0.ex
27d0: 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69 tern "C" {.#endi
27e0: 66 0a 0a 0a 2f 2a 0a 2a 2a 20 50 72 6f 76 69 64 f.../*.** Provid
27f0: 65 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f e the ability to
2800: 20 6f 76 65 72 72 69 64 65 20 6c 69 6e 6b 61 67 override linkag
2810: 65 20 66 65 61 74 75 72 65 73 20 6f 66 20 74 68 e features of th
2820: 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a e interface..*/.
2830: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 45 #ifndef SQLITE_E
2840: 58 54 45 52 4e 0a 23 20 64 65 66 69 6e 65 20 53 XTERN.# define S
2850: 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 65 78 74 QLITE_EXTERN ext
2860: 65 72 6e 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 ern.#endif.#ifnd
2870: 65 66 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 20 ef SQLITE_API.#
2880: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 50 define SQLITE_AP
2890: 49 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 I.#endif.#ifndef
28a0: 20 53 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 20 SQLITE_CDECL.#
28b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 44 define SQLITE_CD
28c0: 45 43 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 ECL.#endif.#ifnd
28d0: 65 66 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c ef SQLITE_STDCAL
28e0: 4c 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 L.# define SQLIT
28f0: 45 5f 53 54 44 43 41 4c 4c 0a 23 65 6e 64 69 66 E_STDCALL.#endif
2900: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f ../*.** These no
2910: 2d 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20 75 -op macros are u
2920: 73 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 sed in front of
2930: 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d 61 interfaces to ma
2940: 72 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 rk those.** inte
2950: 72 66 61 63 65 73 20 61 73 20 65 69 74 68 65 72 rfaces as either
2960: 20 64 65 70 72 65 63 61 74 65 64 20 6f 72 20 65 deprecated or e
2970: 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 xperimental. Ne
2980: 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a w applications.*
2990: 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 * should not use
29a0: 20 64 65 70 72 65 63 61 74 65 64 20 69 6e 74 65 deprecated inte
29b0: 72 66 61 63 65 73 20 2d 20 74 68 65 79 20 61 72 rfaces - they ar
29c0: 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 e supported for
29d0: 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d backwards.** com
29e0: 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e patibility only.
29f0: 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 77 72 Application wr
2a00: 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 iters should be
2a10: 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 65 78 aware that.** ex
2a20: 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 perimental inter
2a30: 66 61 63 65 73 20 61 72 65 20 73 75 62 6a 65 63 faces are subjec
2a40: 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 70 t to change in p
2a50: 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a oint releases..*
2a60: 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f *.** These macro
2a70: 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f 6c 76 s used to resolv
2a80: 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e e to various kin
2a90: 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d ds of compiler m
2aa0: 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75 agic that.** wou
2ab0: 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61 72 6e ld generate warn
2ac0: 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77 68 65 ing messages whe
2ad0: 6e 20 74 68 65 79 20 77 65 72 65 20 75 73 65 64 n they were used
2ae0: 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a 20 63 . But that.** c
2af0: 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 65 6e ompiler magic en
2b00: 64 65 64 20 75 70 20 67 65 6e 65 72 61 74 69 6e ded up generatin
2b10: 67 20 73 75 63 68 20 61 20 66 6c 75 72 72 79 20 g such a flurry
2b20: 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73 0a 2a of bug reports.*
2b30: 2a 20 74 68 61 74 20 77 65 20 68 61 76 65 20 74 * that we have t
2b40: 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20 aken it all out
2b50: 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f and gone back to
2b60: 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a using simple.**
2b70: 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f noop macros..*/
2b80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
2b90: 44 45 50 52 45 43 41 54 45 44 0a 23 64 65 66 69 DEPRECATED.#defi
2ba0: 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 ne SQLITE_EXPERI
2bb0: 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e MENTAL../*.** En
2bc0: 73 75 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f sure these symbo
2bd0: 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 ls were not defi
2be0: 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 ned by some prev
2bf0: 69 6f 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 ious header file
2c00: 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 ..*/.#ifdef SQLI
2c10: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 TE_VERSION.# und
2c20: 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f ef SQLITE_VERSIO
2c30: 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 N.#endif.#ifdef
2c40: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e SQLITE_VERSION_N
2c50: 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 UMBER.# undef SQ
2c60: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d LITE_VERSION_NUM
2c70: 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a BER.#endif../*.*
2c80: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 * CAPI3REF: Comp
2c90: 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 ile-Time Library
2ca0: 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 Version Numbers
2cb0: 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 .**.** ^(The [SQ
2cc0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20 LITE_VERSION] C
2cd0: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 preprocessor mac
2ce0: 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 ro in the sqlite
2cf0: 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 65 76 3.h header.** ev
2d00: 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73 74 72 aluates to a str
2d10: 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74 ing literal that
2d20: 20 69 73 20 74 68 65 20 53 51 4c 69 74 65 20 76 is the SQLite v
2d30: 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a ersion in the.**
2d40: 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20 format "X.Y.Z"
2d50: 77 68 65 72 65 20 58 20 69 73 20 74 68 65 20 6d where X is the m
2d60: 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d ajor version num
2d70: 62 65 72 20 28 61 6c 77 61 79 73 20 33 20 66 6f ber (always 3 fo
2d80: 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 61 6e r.** SQLite3) an
2d90: 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 d Y is the minor
2da0: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 version number
2db0: 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72 65 6c and Z is the rel
2dc0: 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a ease number.)^.*
2dd0: 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f * ^(The [SQLITE_
2de0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 VERSION_NUMBER]
2df0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d C preprocessor m
2e00: 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f acro resolves to
2e10: 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77 an integer.** w
2e20: 69 74 68 20 74 68 65 20 76 61 6c 75 65 20 28 58 ith the value (X
2e30: 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 *1000000 + Y*100
2e40: 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 20 0 + Z) where X,
2e50: 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 68 65 Y, and Z are the
2e60: 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 same.** numbers
2e70: 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 54 45 used in [SQLITE
2e80: 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 _VERSION].)^.**
2e90: 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 The SQLITE_VERSI
2ea0: 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e ON_NUMBER for an
2eb0: 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73 65 20 y given release
2ec0: 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 of SQLite will a
2ed0: 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72 lso.** be larger
2ee0: 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65 61 73 than the releas
2ef0: 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69 74 20 e from which it
2f00: 69 73 20 64 65 72 69 76 65 64 2e 20 20 45 69 74 is derived. Eit
2f10: 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 her Y will.** be
2f20: 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61 held constant a
2f30: 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63 nd Z will be inc
2f40: 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73 65 remented or else
2f50: 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 Y will be incre
2f60: 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 mented.** and Z
2f70: 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20 74 6f will be reset to
2f80: 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e zero..**.** Sin
2f90: 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31 ce version 3.6.1
2fa0: 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 8, SQLite source
2fb0: 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e 20 73 code has been s
2fc0: 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 tored in the.**
2fd0: 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f <a href="http://
2fe0: 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f www.fossil-scm.o
2ff0: 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f 6e 66 rg/">Fossil conf
3000: 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 iguration manage
3010: 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f ment.** system</
3020: 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 a>. ^The SQLITE
3030: 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63 72 6f _SOURCE_ID macro
3040: 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a 2a 2a evaluates to.**
3050: 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 a string which
3060: 69 64 65 6e 74 69 66 69 65 73 20 61 20 70 61 72 identifies a par
3070: 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d 69 6e ticular check-in
3080: 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 of SQLite.** wi
3090: 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69 67 75 thin its configu
30a0: 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e ration managemen
30b0: 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68 65 20 t system. ^The
30c0: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 SQLITE_SOURCE_ID
30d0: 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 .** string conta
30e0: 69 6e 73 20 74 68 65 20 64 61 74 65 20 61 6e 64 ins the date and
30f0: 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63 68 65 time of the che
3100: 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e 64 20 ck-in (UTC) and
3110: 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73 68 20 an SHA1.** hash
3120: 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20 73 6f of the entire so
3130: 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a 2a urce tree..**.**
3140: 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 See also: [sqli
3150: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 te3_libversion()
3160: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c ],.** [sqlite3_l
3170: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 ibversion_number
3180: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6f ()], [sqlite3_so
3190: 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b 73 urceid()],.** [s
31a0: 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d qlite_version()]
31b0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 and [sqlite_sou
31c0: 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23 64 rce_id()]..*/.#d
31d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 efine SQLITE_VER
31e0: 53 49 4f 4e 20 20 20 20 20 20 20 20 22 33 2e 31 SION "3.1
31f0: 32 2e 32 22 0a 23 64 65 66 69 6e 65 20 53 51 4c 2.2".#define SQL
3200: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 ITE_VERSION_NUMB
3210: 45 52 20 33 30 31 32 30 30 32 0a 23 64 65 66 69 ER 3012002.#defi
3220: 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 ne SQLITE_SOURCE
3230: 5f 49 44 20 20 20 20 20 20 22 32 30 31 36 2d 30 _ID "2016-0
3240: 34 2d 31 38 20 31 37 3a 33 30 3a 33 31 20 39 32 4-18 17:30:31 92
3250: 64 63 35 39 66 64 35 61 64 36 36 66 36 34 36 36 dc59fd5ad66f6466
3260: 36 36 30 34 32 65 62 30 34 31 39 35 65 33 61 36 66042eb04195e3a6
3270: 31 61 39 65 38 65 22 0a 0a 2f 2a 0a 2a 2a 20 43 1a9e8e"../*.** C
3280: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d API3REF: Run-Tim
3290: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f e Library Versio
32a0: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 n Numbers.** KEY
32b0: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 WORDS: sqlite3_v
32c0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f ersion, sqlite3_
32d0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 sourceid.**.** T
32e0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 hese interfaces
32f0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 provide the same
3300: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 information as
3310: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 the [SQLITE_VERS
3320: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 ION],.** [SQLITE
3330: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d _VERSION_NUMBER]
3340: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f , and [SQLITE_SO
3350: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 URCE_ID] C prepr
3360: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a ocessor macros.*
3370: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 * but are associ
3380: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 ated with the li
3390: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 brary instead of
33a0: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 the header file
33b0: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a . ^(Cautious.**
33c0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 programmers mig
33d0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72 ht include asser
33e0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 t() statements i
33f0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 n their applicat
3400: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 ion to.** verify
3410: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74 that values ret
3420: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69 urned by these i
3430: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20 nterfaces match
3440: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a the macros in.**
3450: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64 the header, and
3460: 20 74 68 75 73 20 65 6e 73 75 72 65 20 74 68 61 thus ensure tha
3470: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f t the applicatio
3480: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 n is.** compiled
3490: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c with matching l
34a0: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65 ibrary and heade
34b0: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c r files..**.** <
34c0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
34d0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69 .** assert( sqli
34e0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e te3_libversion_n
34f0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f umber()==SQLITE_
3500: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 VERSION_NUMBER )
3510: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 ;.** assert( str
3520: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 cmp(sqlite3_sour
3530: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f ceid(),SQLITE_SO
3540: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a URCE_ID)==0 );.*
3550: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 * assert( strcmp
3560: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 (sqlite3_libvers
3570: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 ion(),SQLITE_VER
3580: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c SION)==0 );.** <
3590: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
35a0: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 e>)^.**.** ^The
35b0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b sqlite3_version[
35c0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e ] string constan
35d0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 t contains the t
35e0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 ext of [SQLITE_V
35f0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f ERSION].** macro
3600: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f . ^The sqlite3_
3610: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e libversion() fun
3620: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 ction returns a
3630: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a pointer to the.*
3640: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 * to the sqlite3
3650: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e _version[] strin
3660: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 g constant. The
3670: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 sqlite3_libvers
3680: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f ion().** functio
3690: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f n is provided fo
36a0: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 r use in DLLs si
36b0: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 nce DLL users us
36c0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 ually do not hav
36d0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65 e.** direct acce
36e0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e ss to string con
36f0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 stants within th
3700: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 e DLL. ^The.**
3710: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 sqlite3_libversi
3720: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 on_number() func
3730: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 tion returns an
3740: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f integer equal to
3750: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 .** [SQLITE_VERS
3760: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 ION_NUMBER]. ^T
3770: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 he sqlite3_sourc
3780: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 eid() function r
3790: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 eturns .** a poi
37a0: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 nter to a string
37b0: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20 constant whose
37c0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d value is the sam
37d0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51 e as the .** [SQ
37e0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 LITE_SOURCE_ID]
37f0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d C preprocessor m
3800: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 acro..**.** See
3810: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 also: [sqlite_ve
3820: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 rsion()] and [sq
3830: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 lite_source_id()
3840: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 ]..*/.SQLITE_API
3850: 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 const char sqli
3860: 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 3d 20 te3_version[] =
3870: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 3b 0a SQLITE_VERSION;.
3880: 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
3890: 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 char *SQLITE_ST
38a0: 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6c 69 DCALL sqlite3_li
38b0: 62 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a bversion(void);.
38c0: 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
38d0: 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 char *SQLITE_ST
38e0: 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 6f DCALL sqlite3_so
38f0: 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 53 51 urceid(void);.SQ
3900: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
3910: 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
3920: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e te3_libversion_n
3930: 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a umber(void);../*
3940: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 .** CAPI3REF: Ru
3950: 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 43 n-Time Library C
3960: 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69 6f ompilation Optio
3970: 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 73 0a 2a ns Diagnostics.*
3980: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
3990: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 3_compileoption_
39a0: 75 73 65 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 used() function
39b0: 72 65 74 75 72 6e 73 20 30 20 6f 72 20 31 20 0a returns 0 or 1 .
39c0: 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 77 68 ** indicating wh
39d0: 65 74 68 65 72 20 74 68 65 20 73 70 65 63 69 66 ether the specif
39e0: 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 73 20 64 ied option was d
39f0: 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63 6f efined at .** co
3a00: 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54 68 mpile time. ^Th
3a10: 65 20 53 51 4c 49 54 45 5f 20 70 72 65 66 69 78 e SQLITE_ prefix
3a20: 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 may be omitted
3a30: 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70 74 from the .** opt
3a40: 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65 64 20 ion name passed
3a50: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 to sqlite3_compi
3a60: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 2e leoption_used().
3a70: 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 .**.** ^The sq
3a80: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 lite3_compileopt
3a90: 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63 74 69 ion_get() functi
3aa0: 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72 61 74 on allows iterat
3ab0: 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 ing.** over the
3ac0: 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73 20 list of options
3ad0: 74 68 61 74 20 77 65 72 65 20 64 65 66 69 6e 65 that were define
3ae0: 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d d at compile tim
3af0: 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69 6e e by.** returnin
3b00: 67 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70 69 g the N-th compi
3b10: 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20 73 le time option s
3b20: 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69 73 tring. ^If N is
3b30: 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a 2a out of range,.*
3b40: 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c * sqlite3_compil
3b50: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 72 65 eoption_get() re
3b60: 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 turns a NULL poi
3b70: 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 51 4c 49 nter. ^The SQLI
3b80: 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20 69 TE_ .** prefix i
3b90: 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 61 s omitted from a
3ba0: 6e 79 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 ny strings retur
3bb0: 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 ned by .** sqlit
3bc0: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e e3_compileoption
3bd0: 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 _get()..**.** ^S
3be0: 75 70 70 6f 72 74 20 66 6f 72 20 74 68 65 20 64 upport for the d
3bf0: 69 61 67 6e 6f 73 74 69 63 20 66 75 6e 63 74 69 iagnostic functi
3c00: 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 ons sqlite3_comp
3c10: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 ileoption_used()
3c20: 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f .** and sqlite3_
3c30: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 compileoption_ge
3c40: 74 28 29 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 t() may be omitt
3c50: 65 64 20 62 79 20 73 70 65 63 69 66 79 69 6e 67 ed by specifying
3c60: 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 the .** [SQLITE
3c70: 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 _OMIT_COMPILEOPT
3c80: 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69 6f ION_DIAGS] optio
3c90: 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d n at compile tim
3ca0: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 e..**.** See als
3cb0: 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 o: SQL functions
3cc0: 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 [sqlite_compile
3cd0: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20 61 option_used()] a
3ce0: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63 6f nd.** [sqlite_co
3cf0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 mpileoption_get(
3d00: 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d 70 )] and the [comp
3d10: 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61 67 ile_options prag
3d20: 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 ma]..*/.#ifndef
3d30: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 SQLITE_OMIT_COMP
3d40: 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 0a ILEOPTION_DIAGS.
3d50: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
3d60: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
3d70: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 lite3_compileopt
3d80: 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20 63 ion_used(const c
3d90: 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a har *zOptName);.
3da0: 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
3db0: 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 char *SQLITE_ST
3dc0: 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f DCALL sqlite3_co
3dd0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 mpileoption_get(
3de0: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a int N);.#endif..
3df0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
3e00: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 Test To See If T
3e10: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 he Library Is Th
3e20: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e readsafe.**.** ^
3e30: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 The sqlite3_thre
3e40: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f adsafe() functio
3e50: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 n returns zero i
3e60: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a f and only if.**
3e70: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 SQLite was comp
3e80: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69 iled with mutexi
3e90: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 ng code omitted
3ea0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 due to the.** [S
3eb0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
3ec0: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
3ed0: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 ption being set
3ee0: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 to 0..**.** SQLi
3ef0: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c te can be compil
3f00: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f ed with or witho
3f10: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 ut mutexes. Whe
3f20: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 n.** the [SQLITE
3f30: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 _THREADSAFE] C p
3f40: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 reprocessor macr
3f50: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 o is 1 or 2, mut
3f60: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 exes.** are enab
3f70: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 led and SQLite i
3f80: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 s threadsafe. W
3f90: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 hen the.** [SQLI
3fa0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d TE_THREADSAFE] m
3fb0: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 acro is 0, .** t
3fc0: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f he mutexes are o
3fd0: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 mitted. Without
3fe0: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 the mutexes, it
3ff0: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 is not safe.**
4000: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f to use SQLite co
4010: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 ncurrently from
4020: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 more than one th
4030: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 read..**.** Enab
4040: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 ling mutexes inc
4050: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 urs a measurable
4060: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e performance pen
4070: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 alty..** So if s
4080: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 peed is of utmos
4090: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 t importance, it
40a0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 makes sense to
40b0: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d disable.** the m
40c0: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 utexes. But for
40d0: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c maximum safety,
40e0: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 mutexes should
40f0: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e be enabled..** ^
4100: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 The default beha
4110: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 vior is for mute
4120: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 xes to be enable
4130: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e d..**.** This in
4140: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 terface can be u
4150: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 sed by an applic
4160: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 ation to make su
4170: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 re that the.** v
4180: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 ersion of SQLite
4190: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b that it is link
41a0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 ing against was
41b0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a compiled with.**
41c0: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 the desired set
41d0: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c ting of the [SQL
41e0: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 ITE_THREADSAFE]
41f0: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 macro..**.** Thi
4200: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 s interface only
4210: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 reports on the
4220: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 compile-time mut
4230: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 ex setting.** of
4240: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
4250: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 EADSAFE] flag.
4260: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
4270: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 piled with.** SQ
4280: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
4290: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 1 or =2 then mut
42a0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 exes are enabled
42b0: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a by default but.
42c0: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 ** can be fully
42d0: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 or partially dis
42e0: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 abled using a ca
42f0: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ll to [sqlite3_c
4300: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 onfig()].** with
4310: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 the verbs [SQLI
4320: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 TE_CONFIG_SINGLE
4330: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 THREAD], [SQLITE
4340: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 _CONFIG_MULTITHR
4350: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c EAD],.** or [SQL
4360: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 ITE_CONFIG_SERIA
4370: 4c 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72 LIZED]. ^(The r
4380: 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 eturn value of t
4390: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 he.** sqlite3_th
43a0: 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 readsafe() funct
43b0: 69 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 ion shows only t
43c0: 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 he compile-time
43d0: 73 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 setting of.** th
43e0: 72 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 read safety, not
43f0: 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 any run-time ch
4400: 61 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 anges to that se
4410: 74 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a tting made by.**
4420: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
4430: 29 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 ). In other word
4440: 73 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 s, the return va
4450: 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 lue from sqlite3
4460: 5f 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a _threadsafe().**
4470: 20 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 is unchanged by
4480: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 calls to sqlite
4490: 33 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 3_config().)^.**
44a0: 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 .** See the [thr
44b0: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 eading mode] doc
44c0: 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 umentation for a
44d0: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d dditional inform
44e0: 61 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 ation..*/.SQLITE
44f0: 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f _API int SQLITE_
4500: 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
4510: 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 29 threadsafe(void)
4520: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
4530: 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e F: Database Conn
4540: 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a ection Handle.**
4550: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 61 KEYWORDS: {data
4560: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d base connection}
4570: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 {database conne
4580: 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 ctions}.**.** Ea
4590: 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 ch open SQLite d
45a0: 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65 atabase is repre
45b0: 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69 6e sented by a poin
45c0: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e ter to an instan
45d0: 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61 ce of.** the opa
45e0: 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e 61 que structure na
45f0: 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20 20 med "sqlite3".
4600: 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f 20 It is useful to
4610: 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 think of an sqli
4620: 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 te3.** pointer a
4630: 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 s an object. Th
4640: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 e [sqlite3_open(
4650: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 )], [sqlite3_ope
4660: 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b n16()], and.** [
4670: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
4680: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 )] interfaces ar
4690: 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f e its constructo
46a0: 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 rs, and [sqlite3
46b0: 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 _close()].** and
46c0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f [sqlite3_close_
46d0: 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64 65 v2()] are its de
46e0: 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65 72 structors. Ther
46f0: 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 e are many other
4700: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 28 .** interfaces (
4710: 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 such as.** [sqli
4720: 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
4730: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 ], [sqlite3_crea
4740: 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 te_function()],
4750: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f and.** [sqlite3_
4760: 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 busy_timeout()]
4770: 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 to name but thre
4780: 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 e) that are meth
4790: 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c ods on an.** sql
47a0: 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a ite3 object..*/.
47b0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
47c0: 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a qlite3 sqlite3;.
47d0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
47e0: 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20 64-Bit Integer
47f0: 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 Types.** KEYWORD
4800: 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 S: sqlite_int64
4810: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a sqlite_uint64.**
4820: 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 .** Because ther
4830: 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c e is no cross-pl
4840: 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 atform way to sp
4850: 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 ecify 64-bit int
4860: 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 eger types.** SQ
4870: 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 Lite includes ty
4880: 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 pedefs for 64-bi
4890: 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 t signed and uns
48a0: 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a igned integers..
48b0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
48c0: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 3_int64 and sqli
48d0: 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 te3_uint64 are t
48e0: 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79 70 he preferred typ
48f0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a e definitions..*
4900: 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 * The sqlite_int
4910: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 64 and sqlite_ui
4920: 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20 73 nt64 types are s
4930: 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 upported for bac
4940: 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 kwards.** compat
4950: 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a ibility only..**
4960: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
4970: 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 _int64 and sqlit
4980: 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 e_int64 types ca
4990: 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 n store integer
49a0: 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 values.** betwee
49b0: 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35 34 n -9223372036854
49c0: 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33 775808 and +9223
49d0: 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37 20 372036854775807
49e0: 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 inclusive. ^The
49f0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 .** sqlite3_uint
4a00: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 64 and sqlite_ui
4a10: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 nt64 types can s
4a20: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c tore integer val
4a30: 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 ues .** between
4a40: 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30 0 and +184467440
4a50: 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c 73709551615 incl
4a60: 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 usive..*/.#ifdef
4a70: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 SQLITE_INT64_TY
4a80: 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c PE. typedef SQL
4a90: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 ITE_INT64_TYPE s
4aa0: 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 qlite_int64;. t
4ab0: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 ypedef unsigned
4ac0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 SQLITE_INT64_TYP
4ad0: 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b E sqlite_uint64;
4ae0: 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f .#elif defined(_
4af0: 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 MSC_VER) || defi
4b00: 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f ned(__BORLANDC__
4b10: 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e ). typedef __in
4b20: 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 t64 sqlite_int64
4b30: 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 ;. typedef unsi
4b40: 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c gned __int64 sql
4b50: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 ite_uint64;.#els
4b60: 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 e. typedef long
4b70: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 long int sqlite
4b80: 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 _int64;. typede
4b90: 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 f unsigned long
4ba0: 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f long int sqlite_
4bb0: 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 uint64;.#endif.t
4bc0: 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e ypedef sqlite_in
4bd0: 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 t64 sqlite3_int6
4be0: 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 4;.typedef sqlit
4bf0: 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 e_uint64 sqlite3
4c00: 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 _uint64;../*.**
4c10: 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 If compiling for
4c20: 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 a processor tha
4c30: 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 t lacks floating
4c40: 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a point support,.
4c50: 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69 6e ** substitute in
4c60: 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 teger for floati
4c70: 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 ng-point..*/.#if
4c80: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f def SQLITE_OMIT_
4c90: 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 FLOATING_POINT.#
4ca0: 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 define double s
4cb0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e qlite3_int64.#en
4cc0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 dif../*.** CAPI3
4cd0: 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 REF: Closing A D
4ce0: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 atabase Connecti
4cf0: 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 on.** DESTRUCTOR
4d00: 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 : sqlite3.**.**
4d10: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f ^The sqlite3_clo
4d20: 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 se() and sqlite3
4d30: 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75 74 _close_v2() rout
4d40: 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75 63 ines are destruc
4d50: 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 tors.** for the
4d60: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 [sqlite3] object
4d70: 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 ..** ^Calls to s
4d80: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 qlite3_close() a
4d90: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 nd sqlite3_close
4da0: 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53 51 _v2() return [SQ
4db0: 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 74 LITE_OK] if.** t
4dc0: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a he [sqlite3] obj
4dd0: 65 63 74 20 69 73 20 73 75 63 63 65 73 73 66 75 ect is successfu
4de0: 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61 6e lly destroyed an
4df0: 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 d all associated
4e00: 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61 72 .** resources ar
4e10: 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a e deallocated..*
4e20: 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 *.** ^If the dat
4e30: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
4e40: 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 is associated w
4e50: 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 ith unfinalized
4e60: 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 prepared.** stat
4e70: 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e 69 ements or unfini
4e80: 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63 shed sqlite3_bac
4e90: 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65 6e kup objects then
4ea0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 sqlite3_close()
4eb0: 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20 74 .** will leave t
4ec0: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
4ed0: 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64 20 ection open and
4ee0: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 return [SQLITE_B
4ef0: 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c USY]..** ^If sql
4f00: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 ite3_close_v2()
4f10: 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 75 is called with u
4f20: 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 nfinalized prepa
4f30: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a red statements.*
4f40: 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69 73 * and/or unfinis
4f50: 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b hed sqlite3_back
4f60: 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64 61 ups, then the da
4f70: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
4f80: 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20 n becomes.** an
4f90: 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69 65 unusable "zombie
4fa0: 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75 74 " which will aut
4fb0: 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64 65 omatically be de
4fc0: 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20 74 allocated when t
4fd0: 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70 61 he.** last prepa
4fe0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 red statement is
4ff0: 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74 68 finalized or th
5000: 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 62 e last sqlite3_b
5010: 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e 69 ackup is.** fini
5020: 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74 shed. The sqlit
5030: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 6e e3_close_v2() in
5040: 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65 6e terface is inten
5050: 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74 68 ded for use with
5060: 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61 67 .** host languag
5070: 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72 62 es that are garb
5080: 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20 61 age collected, a
5090: 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72 64 nd where the ord
50a0: 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 64 er in which.** d
50b0: 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20 63 estructors are c
50c0: 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72 61 alled is arbitra
50d0: 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 ry..**.** Applic
50e0: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 ations should [s
50f0: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 qlite3_finalize
5100: 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 | finalize] all
5110: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
5120: 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 ents],.** [sqlit
5130: 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 e3_blob_close |
5140: 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 close] all [BLOB
5150: 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20 0a handles], and .
5160: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b ** [sqlite3_back
5170: 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e 69 up_finish | fini
5180: 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33 sh] all [sqlite3
5190: 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 _backup] objects
51a0: 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 associated.** w
51b0: 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65 33 ith the [sqlite3
51c0: 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20 74 ] object prior t
51d0: 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 o attempting to
51e0: 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63 74 close the object
51f0: 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 . ^If.** sqlite
5200: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 3_close_v2() is
5210: 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61 74 called on a [dat
5220: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
5230: 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61 73 ] that still has
5240: 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 .** outstanding
5250: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
5260: 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e ents], [BLOB han
5270: 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a dles], and/or.**
5280: 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 [sqlite3_backup
5290: 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 69 ] objects then i
52a0: 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 t returns [SQLIT
52b0: 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64 65 E_OK] and the de
52c0: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 allocation.** of
52d0: 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64 65 resources is de
52e0: 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c ferred until all
52f0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
5300: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 ments], [BLOB ha
5310: 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b ndles],.** and [
5320: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 sqlite3_backup]
5330: 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73 6f objects are also
5340: 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a destroyed..**.*
5350: 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 * ^If an [sqlite
5360: 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65 73 3] object is des
5370: 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20 74 troyed while a t
5380: 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 ransaction is op
5390: 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 en,.** the trans
53a0: 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 action is automa
53b0: 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 tically rolled b
53c0: 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 ack..**.** The C
53d0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 parameter to [s
53e0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d qlite3_close(C)]
53f0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c and [sqlite3_cl
5400: 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 ose_v2(C)].** mu
5410: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e st be either a N
5420: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f ULL.** pointer o
5430: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f r an [sqlite3] o
5440: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 bject pointer ob
5450: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b tained.** from [
5460: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c sqlite3_open()],
5470: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 [sqlite3_open16
5480: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 ()], or.** [sqli
5490: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 te3_open_v2()],
54a0: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 and not previous
54b0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 ly closed..** ^C
54c0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 alling sqlite3_c
54d0: 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74 65 lose() or sqlite
54e0: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69 74 3_close_v2() wit
54f0: 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 h a NULL pointer
5500: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 .** argument is
5510: 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 a harmless no-op
5520: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
5530: 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 int SQLITE_STDCA
5540: 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 LL sqlite3_close
5550: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 (sqlite3*);.SQLI
5560: 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
5570: 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
5580: 33 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 3_close_v2(sqlit
5590: 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 e3*);../*.** The
55a0: 20 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c type for a call
55b0: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a back function..*
55c0: 2a 20 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 * This is legacy
55d0: 20 61 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e and deprecated.
55e0: 20 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 It is included
55f0: 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a for historical.
5600: 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 ** compatibility
5610: 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 and is not docu
5620: 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 mented..*/.typed
5630: 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 ef int (*sqlite3
5640: 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a _callback)(void*
5650: 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 ,int,char**, cha
5660: 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 r**);../*.** CAP
5670: 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 I3REF: One-Step
5680: 51 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 Query Execution
5690: 49 6e 74 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 Interface.** MET
56a0: 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a HOD: sqlite3.**.
56b0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 ** The sqlite3_e
56c0: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 xec() interface
56d0: 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 is a convenience
56e0: 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a wrapper around.
56f0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
5700: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 are_v2()], [sqli
5710: 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 te3_step()], and
5720: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
5730: 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 ze()],.** that a
5740: 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61 llows an applica
5750: 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 tion to run mult
5760: 69 70 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20 iple statements
5770: 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 of SQL.** withou
5780: 74 20 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20 t having to use
5790: 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e a lot of C code.
57a0: 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c .**.** ^The sql
57b0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 ite3_exec() inte
57c0: 72 66 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 rface runs zero
57d0: 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e or more UTF-8 en
57e0: 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f coded,.** semico
57f0: 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c lon-separate SQL
5800: 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 statements pass
5810: 65 64 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 ed into its 2nd
5820: 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 argument,.** in
5830: 74 68 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 the context of t
5840: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
5850: 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 nection] passed
5860: 69 6e 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a in as its 1st.**
5870: 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 argument. ^If
5880: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e the callback fun
5890: 63 74 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 ction of the 3rd
58a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 argument to.**
58b0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 sqlite3_exec() i
58c0: 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e s not NULL, then
58d0: 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 it is invoked f
58e0: 6f 72 20 65 61 63 68 20 72 65 73 75 6c 74 20 72 or each result r
58f0: 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 ow.** coming out
5900: 20 6f 66 20 74 68 65 20 65 76 61 6c 75 61 74 65 of the evaluate
5910: 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 d SQL statements
5920: 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 . ^The 4th argu
5930: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 ment to.** sqlit
5940: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c e3_exec() is rel
5950: 61 79 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 ayed through to
5960: 74 68 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74 the 1st argument
5970: 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c of each.** call
5980: 62 61 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e back invocation.
5990: 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 ^If the callba
59a0: 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 ck pointer to sq
59b0: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 lite3_exec().**
59c0: 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f is NULL, then no
59d0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 callback is eve
59e0: 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 r invoked and re
59f0: 73 75 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a sult rows are.**
5a00: 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 ignored..**.**
5a10: 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 ^If an error occ
5a20: 75 72 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61 urs while evalua
5a30: 74 69 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61 ting the SQL sta
5a40: 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 tements passed i
5a50: 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 nto.** sqlite3_e
5a60: 78 65 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63 xec(), then exec
5a70: 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 ution of the cur
5a80: 72 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73 rent statement s
5a90: 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 tops and.** subs
5aa0: 65 71 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 equent statement
5ab0: 73 20 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20 s are skipped.
5ac0: 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72 61 ^If the 5th para
5ad0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
5ae0: 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f _exec().** is no
5af0: 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 t NULL then any
5b00: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 error message is
5b10: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 written into me
5b20: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a mory obtained.**
5b30: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d from [sqlite3_m
5b40: 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 alloc()] and pas
5b50: 73 65 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 sed back through
5b60: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 the 5th paramet
5b70: 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 er..** To avoid
5b80: 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 memory leaks, th
5b90: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 e application sh
5ba0: 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c ould invoke [sql
5bb0: 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 ite3_free()].**
5bc0: 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 on error message
5bd0: 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 strings returne
5be0: 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 d through the 5t
5bf0: 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a h parameter of.*
5c00: 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 * sqlite3_exec()
5c10: 20 61 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 after the error
5c20: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 message string
5c30: 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 is no longer nee
5c40: 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ded..** ^If the
5c50: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 5th parameter to
5c60: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
5c70: 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 is not NULL and
5c80: 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 no errors.** occ
5c90: 75 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 ur, then sqlite3
5ca0: 5f 65 78 65 63 28 29 20 73 65 74 73 20 74 68 65 _exec() sets the
5cb0: 20 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20 pointer in its
5cc0: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 5th parameter to
5cd0: 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 .** NULL before
5ce0: 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a returning..**.**
5cf0: 20 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f ^If an sqlite3_
5d00: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 exec() callback
5d10: 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f returns non-zero
5d20: 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 , the sqlite3_ex
5d30: 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 ec().** routine
5d40: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 returns SQLITE_A
5d50: 42 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76 BORT without inv
5d60: 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 oking the callba
5d70: 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 ck again and.**
5d80: 77 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 without running
5d90: 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 53 any subsequent S
5da0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a QL statements..*
5db0: 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 *.** ^The 2nd ar
5dc0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 gument to the sq
5dd0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c lite3_exec() cal
5de0: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 lback function i
5df0: 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 s the.** number
5e00: 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 of columns in th
5e10: 65 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 e result. ^The
5e20: 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 3rd argument to
5e30: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 the sqlite3_exec
5e40: 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 ().** callback i
5e50: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f s an array of po
5e60: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 inters to string
5e70: 73 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66 s obtained as if
5e80: 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 from.** [sqlite
5e90: 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 3_column_text()]
5ea0: 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63 , one for each c
5eb0: 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 olumn. ^If an e
5ec0: 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 lement of a.** r
5ed0: 65 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c esult row is NUL
5ee0: 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65 L then the corre
5ef0: 73 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 sponding string
5f00: 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a pointer for the.
5f10: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 ** sqlite3_exec(
5f20: 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 ) callback is a
5f30: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e NULL pointer. ^
5f40: 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 The 4th argument
5f50: 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 to the.** sqlit
5f60: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 e3_exec() callba
5f70: 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f ck is an array o
5f80: 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 f pointers to st
5f90: 72 69 6e 67 73 20 77 68 65 72 65 20 65 61 63 68 rings where each
5fa0: 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73 .** entry repres
5fb0: 65 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 ents the name of
5fc0: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 corresponding r
5fd0: 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 esult column as
5fe0: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d obtained.** from
5ff0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
6000: 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 _name()]..**.**
6010: 5e 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 ^If the 2nd para
6020: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
6030: 5f 65 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c _exec() is a NUL
6040: 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 L pointer, a poi
6050: 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d nter.** to an em
6060: 70 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 pty string, or a
6070: 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f pointer that co
6080: 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 ntains only whit
6090: 65 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a espace and/or .*
60a0: 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 * SQL comments,
60b0: 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 then no SQL stat
60c0: 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 ements are evalu
60d0: 61 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 ated and the dat
60e0: 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 abase.** is not
60f0: 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 changed..**.** R
6100: 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a estrictions:.**.
6110: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ul>.** <li>
6120: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 The application
6130: 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61 74 must ensure that
6140: 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 the 1st paramet
6150: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 er to sqlite3_ex
6160: 65 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 ec().** is
6170: 61 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e a valid and open
6180: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
6190: 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 ction]..** <li>
61a0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 The application
61b0: 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 must not close t
61c0: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
61d0: 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 nection] specifi
61e0: 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 ed by.** th
61f0: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 e 1st parameter
6200: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 to sqlite3_exec(
6210: 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f ) while sqlite3_
6220: 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e exec() is runnin
6230: 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 g..** <li> The a
6240: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 pplication must
6250: 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53 not modify the S
6260: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 QL statement tex
6270: 74 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a t passed into.**
6280: 20 20 20 20 20 20 74 68 65 20 32 6e 64 20 70 61 the 2nd pa
6290: 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 rameter of sqlit
62a0: 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 e3_exec() while
62b0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 sqlite3_exec() i
62c0: 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f s running..** </
62d0: 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 ul>.*/.SQLITE_AP
62e0: 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
62f0: 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 78 65 CALL sqlite3_exe
6300: 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 c(. sqlite3*,
6310: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
6320: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
6330: 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 /* An open datab
6340: 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 ase */. const c
6350: 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 har *sql,
6360: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
6370: 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 /* SQL to be
6380: 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 evaluated */.
6390: 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 int (*callback)(
63a0: 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a void*,int,char**
63b0: 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 ,char**), /* Ca
63c0: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
63d0: 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 */. void *,
63e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
63f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
6400: 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 /* 1st argument
6410: 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 to callback */.
6420: 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 char **errmsg
6430: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
6440: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 /* E
6450: 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e rror msg written
6460: 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a here */.);../*.
6470: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 ** CAPI3REF: Res
6480: 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 ult Codes.** KEY
6490: 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 WORDS: {result c
64a0: 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d ode definitions}
64b0: 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 .**.** Many SQLi
64c0: 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 te functions ret
64d0: 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 urn an integer r
64e0: 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 esult code from
64f0: 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a the set shown.**
6500: 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 here in order t
6510: 6f 20 69 6e 64 69 63 61 74 65 20 73 75 63 63 65 o indicate succe
6520: 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a ss or failure..*
6530: 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63 *.** New error c
6540: 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 odes may be adde
6550: 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 d in future vers
6560: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a ions of SQLite..
6570: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
6580: 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 [extended result
6590: 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e code definition
65a0: 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 s].*/.#define SQ
65b0: 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 LITE_OK
65c0: 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 0 /* Success
65d0: 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a ful result */./*
65e0: 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 beginning-of-er
65f0: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 ror-codes */.#de
6600: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f fine SQLITE_ERRO
6610: 52 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 R 1 /*
6620: 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 SQL error or mis
6630: 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f sing database */
6640: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6650: 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 INTERNAL 2
6660: 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 /* Internal log
6670: 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 ic error in SQLi
6680: 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 te */.#define SQ
6690: 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 LITE_PERM
66a0: 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 3 /* Access
66b0: 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 permission denie
66c0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
66d0: 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 ITE_ABORT
66e0: 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 4 /* Callback
66f0: 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 routine request
6700: 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 ed an abort */.#
6710: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 define SQLITE_BU
6720: 53 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f SY 5 /
6730: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66 * The database f
6740: 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f ile is locked */
6750: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6760: 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 LOCKED 6
6770: 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 /* A table in t
6780: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c he database is l
6790: 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 ocked */.#define
67a0: 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 SQLITE_NOMEM
67b0: 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 7 /* A ma
67c0: 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f lloc() failed */
67d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
67e0: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 READONLY 8
67f0: 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 /* Attempt to w
6800: 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 rite a readonly
6810: 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 database */.#def
6820: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 ine SQLITE_INTER
6830: 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f RUPT 9 /* O
6840: 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 peration termina
6850: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 ted by sqlite3_i
6860: 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 nterrupt()*/.#de
6870: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
6880: 52 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 R 10 /*
6890: 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 Some kind of dis
68a0: 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 k I/O error occu
68b0: 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 rred */.#define
68c0: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 SQLITE_CORRUPT
68d0: 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 11 /* The d
68e0: 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 atabase disk ima
68f0: 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 ge is malformed
6900: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
6910: 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 E_NOTFOUND 12
6920: 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 /* Unknown op
6930: 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f code in sqlite3_
6940: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a file_control() *
6950: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
6960: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 _FULL 13
6970: 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 /* Insertion f
6980: 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 ailed because da
6990: 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a tabase is full *
69a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
69b0: 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 _CANTOPEN 14
69c0: 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f /* Unable to o
69d0: 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 pen the database
69e0: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 file */.#define
69f0: 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c SQLITE_PROTOCOL
6a00: 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 15 /* Data
6a10: 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 base lock protoc
6a20: 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 ol error */.#def
6a30: 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 ine SQLITE_EMPTY
6a40: 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 16 /* D
6a50: 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 atabase is empty
6a60: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
6a70: 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 TE_SCHEMA 1
6a80: 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 7 /* The datab
6a90: 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 ase schema chang
6aa0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ed */.#define SQ
6ab0: 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 LITE_TOOBIG
6ac0: 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 18 /* String
6ad0: 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 or BLOB exceeds
6ae0: 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 size limit */.#d
6af0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
6b00: 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a STRAINT 19 /*
6b10: 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f Abort due to co
6b20: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 nstraint violati
6b30: 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 on */.#define SQ
6b40: 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 LITE_MISMATCH
6b50: 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 20 /* Data ty
6b60: 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 pe mismatch */.#
6b70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 define SQLITE_MI
6b80: 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f SUSE 21 /
6b90: 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 * Library used i
6ba0: 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 ncorrectly */.#d
6bb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c efine SQLITE_NOL
6bc0: 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a FS 22 /*
6bd0: 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 Uses OS feature
6be0: 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 s not supported
6bf0: 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 on host */.#defi
6c00: 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 ne SQLITE_AUTH
6c10: 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 23 /* Au
6c20: 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 thorization deni
6c30: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ed */.#define SQ
6c40: 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 LITE_FORMAT
6c50: 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 24 /* Auxilia
6c60: 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d ry database form
6c70: 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 at error */.#def
6c80: 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 ine SQLITE_RANGE
6c90: 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 25 /* 2
6ca0: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 nd parameter to
6cb0: 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 sqlite3_bind out
6cc0: 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 of range */.#de
6cd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 fine SQLITE_NOTA
6ce0: 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 DB 26 /*
6cf0: 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 File opened that
6d00: 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 is not a databa
6d10: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 se file */.#defi
6d20: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 ne SQLITE_NOTICE
6d30: 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 4e 6f 27 /* No
6d40: 74 69 66 69 63 61 74 69 6f 6e 73 20 66 72 6f 6d tifications from
6d50: 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a sqlite3_log() *
6d60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
6d70: 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 32 38 20 _WARNING 28
6d80: 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20 66 72 /* Warnings fr
6d90: 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 om sqlite3_log()
6da0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
6db0: 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 TE_ROW 1
6dc0: 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 00 /* sqlite3_s
6dd0: 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 tep() has anothe
6de0: 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 r row ready */.#
6df0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f define SQLITE_DO
6e00: 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 20 2f NE 101 /
6e10: 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 * sqlite3_step()
6e20: 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 has finished ex
6e30: 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e ecuting */./* en
6e40: 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 d-of-error-codes
6e50: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 */../*.** CAPI3
6e60: 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 REF: Extended Re
6e70: 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 sult Codes.** KE
6e80: 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 YWORDS: {extende
6e90: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 d result code de
6ea0: 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a finitions}.**.**
6eb0: 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 In its default
6ec0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 configuration, S
6ed0: 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e QLite API routin
6ee0: 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 es return one of
6ef0: 20 33 30 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 30 integer.** [
6f00: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 result codes].
6f10: 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 However, experie
6f20: 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 nce has shown th
6f30: 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 at many of.** th
6f40: 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ese result codes
6f50: 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d are too coarse-
6f60: 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 grained. They d
6f70: 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 o not provide as
6f80: 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 .** much informa
6f90: 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c tion about probl
6fa0: 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 ems as programme
6fb0: 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 rs might like.
6fc0: 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a In an effort to.
6fd0: 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c ** address this,
6fe0: 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 newer versions
6ff0: 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 of SQLite (versi
7000: 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 on 3.3.8 and lat
7010: 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 er) include.** s
7020: 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 upport for addit
7030: 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 ional result cod
7040: 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 es that provide
7050: 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e more detailed in
7060: 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f formation.** abo
7070: 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 ut errors. These
7080: 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c [extended resul
7090: 74 20 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 t codes] are ena
70a0: 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 bled or disabled
70b0: 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 .** on a per dat
70c0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
70d0: 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 basis using the
70e0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 .** [sqlite3_ext
70f0: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 ended_result_cod
7100: 65 73 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 es()] API. Or,
7110: 74 68 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 the extended cod
7120: 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 e for.** the mos
7130: 74 20 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 t recent error c
7140: 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 an be obtained u
7150: 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 sing.** [sqlite3
7160: 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 _extended_errcod
7170: 65 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 e()]..*/.#define
7180: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 SQLITE_IOERR_RE
7190: 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 AD
71a0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
71b0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (1<<8)).#define
71c0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f SQLITE_IOERR_SHO
71d0: 52 54 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 RT_READ (
71e0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
71f0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 2<<8)).#define S
7200: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 QLITE_IOERR_WRIT
7210: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 E (S
7220: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 QLITE_IOERR | (3
7230: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
7240: 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 LITE_IOERR_FSYNC
7250: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
7260: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c LITE_IOERR | (4<
7270: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
7280: 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 ITE_IOERR_DIR_FS
7290: 59 4e 43 20 20 20 20 20 20 20 20 20 28 53 51 4c YNC (SQL
72a0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c ITE_IOERR | (5<<
72b0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
72c0: 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 TE_IOERR_TRUNCAT
72d0: 45 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 E (SQLI
72e0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 TE_IOERR | (6<<8
72f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
7300: 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 E_IOERR_FSTAT
7310: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
7320: 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 E_IOERR | (7<<8)
7330: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
7340: 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 _IOERR_UNLOCK
7350: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
7360: 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 _IOERR | (8<<8))
7370: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
7380: 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 IOERR_RDLOCK
7390: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
73a0: 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a IOERR | (9<<8)).
73b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
73c0: 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 OERR_DELETE
73d0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
73e0: 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a OERR | (10<<8)).
73f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
7400: 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 OERR_BLOCKED
7410: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
7420: 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a OERR | (11<<8)).
7430: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
7440: 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 OERR_NOMEM
7450: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
7460: 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a OERR | (12<<8)).
7470: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
7480: 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 OERR_ACCESS
7490: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
74a0: 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a OERR | (13<<8)).
74b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
74c0: 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 OERR_CHECKRESERV
74d0: 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 EDLOCK (SQLITE_I
74e0: 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a OERR | (14<<8)).
74f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
7500: 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 OERR_LOCK
7510: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
7520: 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a OERR | (15<<8)).
7530: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
7540: 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 OERR_CLOSE
7550: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
7560: 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a OERR | (16<<8)).
7570: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
7580: 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 OERR_DIR_CLOSE
7590: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
75a0: 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a OERR | (17<<8)).
75b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
75c0: 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 OERR_SHMOPEN
75d0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
75e0: 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a OERR | (18<<8)).
75f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
7600: 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 OERR_SHMSIZE
7610: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
7620: 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a OERR | (19<<8)).
7630: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
7640: 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 OERR_SHMLOCK
7650: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
7660: 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a OERR | (20<<8)).
7670: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
7680: 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 OERR_SHMMAP
7690: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
76a0: 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a OERR | (21<<8)).
76b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
76c0: 4f 45 52 52 5f 53 45 45 4b 20 20 20 20 20 20 20 OERR_SEEK
76d0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
76e0: 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a OERR | (22<<8)).
76f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
7700: 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e OERR_DELETE_NOEN
7710: 54 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 T (SQLITE_I
7720: 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38 29 29 0a OERR | (23<<8)).
7730: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
7740: 4f 45 52 52 5f 4d 4d 41 50 20 20 20 20 20 20 20 OERR_MMAP
7750: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
7760: 4f 45 52 52 20 7c 20 28 32 34 3c 3c 38 29 29 0a OERR | (24<<8)).
7770: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
7780: 4f 45 52 52 5f 47 45 54 54 45 4d 50 50 41 54 48 OERR_GETTEMPPATH
7790: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
77a0: 4f 45 52 52 20 7c 20 28 32 35 3c 3c 38 29 29 0a OERR | (25<<8)).
77b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
77c0: 4f 45 52 52 5f 43 4f 4e 56 50 41 54 48 20 20 20 OERR_CONVPATH
77d0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
77e0: 4f 45 52 52 20 7c 20 28 32 36 3c 3c 38 29 29 0a OERR | (26<<8)).
77f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
7800: 4f 45 52 52 5f 56 4e 4f 44 45 20 20 20 20 20 20 OERR_VNODE
7810: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
7820: 4f 45 52 52 20 7c 20 28 32 37 3c 3c 38 29 29 0a OERR | (27<<8)).
7830: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
7840: 4f 45 52 52 5f 41 55 54 48 20 20 20 20 20 20 20 OERR_AUTH
7850: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
7860: 4f 45 52 52 20 7c 20 28 32 38 3c 3c 38 29 29 0a OERR | (28<<8)).
7870: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
7880: 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 OCKED_SHAREDCACH
7890: 45 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c E (SQLITE_L
78a0: 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 OCKED | (1<<8))
78b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
78c0: 42 55 53 59 5f 52 45 43 4f 56 45 52 59 20 20 20 BUSY_RECOVERY
78d0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
78e0: 42 55 53 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 BUSY | (1<<8)
78f0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
7900: 5f 42 55 53 59 5f 53 4e 41 50 53 48 4f 54 20 20 _BUSY_SNAPSHOT
7910: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
7920: 5f 42 55 53 59 20 20 20 7c 20 20 28 32 3c 3c 38 _BUSY | (2<<8
7930: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
7940: 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d E_CANTOPEN_NOTEM
7950: 50 44 49 52 20 20 20 20 20 20 28 53 51 4c 49 54 PDIR (SQLIT
7960: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c E_CANTOPEN | (1<
7970: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
7980: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 ITE_CANTOPEN_ISD
7990: 49 52 20 20 20 20 20 20 20 20 20 20 28 53 51 4c IR (SQL
79a0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 ITE_CANTOPEN | (
79b0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 2<<8)).#define S
79c0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 QLITE_CANTOPEN_F
79d0: 55 4c 4c 50 41 54 48 20 20 20 20 20 20 20 28 53 ULLPATH (S
79e0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c QLITE_CANTOPEN |
79f0: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (3<<8)).#define
7a00: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e SQLITE_CANTOPEN
7a10: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 _CONVPATH
7a20: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e (SQLITE_CANTOPEN
7a30: 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 | (4<<8)).#defi
7a40: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 ne SQLITE_CORRUP
7a50: 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 20 T_VTAB
7a60: 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 (SQLITE_CORRUP
7a70: 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 T | (1<<8)).#def
7a80: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f ine SQLITE_READO
7a90: 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 NLY_RECOVERY
7aa0: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f (SQLITE_READO
7ab0: 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 NLY | (1<<8)).#d
7ac0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 efine SQLITE_REA
7ad0: 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 DONLY_CANTLOCK
7ae0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 (SQLITE_REA
7af0: 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a DONLY | (2<<8)).
7b00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
7b10: 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b EADONLY_ROLLBACK
7b20: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 (SQLITE_R
7b30: 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 EADONLY | (3<<8)
7b40: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
7b50: 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 _READONLY_DBMOVE
7b60: 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 D (SQLITE
7b70: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c _READONLY | (4<<
7b80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
7b90: 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 TE_ABORT_ROLLBAC
7ba0: 4b 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 K (SQLI
7bb0: 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c 38 TE_ABORT | (2<<8
7bc0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
7bd0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48 45 E_CONSTRAINT_CHE
7be0: 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 CK (SQLIT
7bf0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 E_CONSTRAINT | (
7c00: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 1<<8)).#define S
7c10: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
7c20: 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 28 53 _COMMITHOOK (S
7c30: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
7c40: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 | (2<<8)).#defi
7c50: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 ne SQLITE_CONSTR
7c60: 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 59 20 AINT_FOREIGNKEY
7c70: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 (SQLITE_CONSTR
7c80: 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29 0a 23 AINT | (3<<8)).#
7c90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
7ca0: 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54 49 4f NSTRAINT_FUNCTIO
7cb0: 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f N (SQLITE_CO
7cc0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c 3c 38 NSTRAINT | (4<<8
7cd0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
7ce0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 E_CONSTRAINT_NOT
7cf0: 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c 49 54 NULL (SQLIT
7d00: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 E_CONSTRAINT | (
7d10: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 5<<8)).#define S
7d20: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
7d30: 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20 28 53 _PRIMARYKEY (S
7d40: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
7d50: 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 | (6<<8)).#defi
7d60: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 ne SQLITE_CONSTR
7d70: 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20 20 20 AINT_TRIGGER
7d80: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 (SQLITE_CONSTR
7d90: 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29 0a 23 AINT | (7<<8)).#
7da0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
7db0: 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55 45 20 NSTRAINT_UNIQUE
7dc0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f (SQLITE_CO
7dd0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c 3c 38 NSTRAINT | (8<<8
7de0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
7df0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54 41 E_CONSTRAINT_VTA
7e00: 42 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 B (SQLIT
7e10: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 E_CONSTRAINT | (
7e20: 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 9<<8)).#define S
7e30: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
7e40: 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20 28 53 _ROWID (S
7e50: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
7e60: 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 |(10<<8)).#defi
7e70: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 ne SQLITE_NOTICE
7e80: 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 20 20 _RECOVER_WAL
7e90: 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 (SQLITE_NOTICE
7ea0: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 | (1<<8)).#defi
7eb0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 ne SQLITE_NOTICE
7ec0: 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 _RECOVER_ROLLBAC
7ed0: 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 K (SQLITE_NOTICE
7ee0: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 | (2<<8)).#defi
7ef0: 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e ne SQLITE_WARNIN
7f00: 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20 20 20 G_AUTOINDEX
7f10: 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e (SQLITE_WARNIN
7f20: 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 G | (1<<8)).#def
7f30: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 5f ine SQLITE_AUTH_
7f40: 55 53 45 52 20 20 20 20 20 20 20 20 20 20 20 20 USER
7f50: 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54 48 20 (SQLITE_AUTH
7f60: 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a | (1<<8))../*.**
7f70: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 CAPI3REF: Flags
7f80: 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f For File Open O
7f90: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 perations.**.**
7fa0: 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 These bit values
7fb0: 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f are intended fo
7fc0: 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 r use in the.**
7fd0: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 3rd parameter to
7fe0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 the [sqlite3_op
7ff0: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 en_v2()] interfa
8000: 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 ce and.** in the
8010: 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 4th parameter t
8020: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 o the [sqlite3_v
8030: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 fs.xOpen] method
8040: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
8050: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c ITE_OPEN_READONL
8060: 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 Y 0x0000
8070: 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0001 /* Ok for
8080: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
8090: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
80a0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 ITE_OPEN_READWRI
80b0: 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 TE 0x0000
80c0: 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0002 /* Ok for
80d0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
80e0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
80f0: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 ITE_OPEN_CREATE
8100: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
8110: 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0004 /* Ok for
8120: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
8130: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
8140: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f ITE_OPEN_DELETEO
8150: 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 NCLOSE 0x0000
8160: 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0008 /* VFS onl
8170: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
8180: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 ITE_OPEN_EXCLUSI
8190: 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 VE 0x0000
81a0: 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0010 /* VFS onl
81b0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
81c0: 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f ITE_OPEN_AUTOPRO
81d0: 58 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30 XY 0x0000
81e0: 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0020 /* VFS onl
81f0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
8200: 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 ITE_OPEN_URI
8210: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
8220: 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0040 /* Ok for
8230: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
8240: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
8250: 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 ITE_OPEN_MEMORY
8260: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
8270: 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0080 /* Ok for
8280: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
8290: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
82a0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 ITE_OPEN_MAIN_DB
82b0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
82c0: 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0100 /* VFS onl
82d0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
82e0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 ITE_OPEN_TEMP_DB
82f0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
8300: 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0200 /* VFS onl
8310: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
8320: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 ITE_OPEN_TRANSIE
8330: 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 NT_DB 0x0000
8340: 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0400 /* VFS onl
8350: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
8360: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f ITE_OPEN_MAIN_JO
8370: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 URNAL 0x0000
8380: 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0800 /* VFS onl
8390: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
83a0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f ITE_OPEN_TEMP_JO
83b0: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 URNAL 0x0000
83c0: 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 1000 /* VFS onl
83d0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
83e0: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 ITE_OPEN_SUBJOUR
83f0: 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 NAL 0x0000
8400: 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 2000 /* VFS onl
8410: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
8420: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f ITE_OPEN_MASTER_
8430: 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 JOURNAL 0x0000
8440: 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 4000 /* VFS onl
8450: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
8460: 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 ITE_OPEN_NOMUTEX
8470: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
8480: 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 8000 /* Ok for
8490: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
84a0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
84b0: 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 ITE_OPEN_FULLMUT
84c0: 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 EX 0x0001
84d0: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0000 /* Ok for
84e0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
84f0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
8500: 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 ITE_OPEN_SHAREDC
8510: 41 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32 ACHE 0x0002
8520: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0000 /* Ok for
8530: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
8540: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
8550: 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 ITE_OPEN_PRIVATE
8560: 43 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34 CACHE 0x0004
8570: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0000 /* Ok for
8580: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
8590: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
85a0: 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 ITE_OPEN_WAL
85b0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38 0x0008
85c0: 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0000 /* VFS onl
85d0: 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 y */../* Reserve
85e0: 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 d:
85f0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 46 0x00F
8600: 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 00000 */../*.**
8610: 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 CAPI3REF: Device
8620: 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 Characteristics
8630: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 .**.** The xDevi
8640: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 ceCharacteristic
8650: 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 s method of the
8660: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 [sqlite3_io_meth
8670: 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 ods].** object r
8680: 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 eturns an intege
8690: 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63 r which is a vec
86a0: 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 tor of these.**
86b0: 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 bit values expre
86c0: 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 ssing I/O charac
86d0: 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 teristics of the
86e0: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a mass storage.**
86f0: 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c device that hol
8700: 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 ds the file that
8710: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f the [sqlite3_io
8720: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 _methods].** ref
8730: 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 ers to..**.** Th
8740: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
8750: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d TOMIC property m
8760: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 eans that all wr
8770: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 ites of.** any s
8780: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 ize are atomic.
8790: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
87a0: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 P_ATOMICnnn valu
87b0: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 es.** mean that
87c0: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 writes of blocks
87d0: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 that are nnn by
87e0: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a tes in size and.
87f0: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 ** are aligned t
8800: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 o an address whi
8810: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 ch is an integer
8820: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 multiple of.**
8830: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 nnn are atomic.
8840: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
8850: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 P_SAFE_APPEND va
8860: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 lue means.** tha
8870: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 t when data is a
8880: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c ppended to a fil
8890: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 e, the data is a
88a0: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 ppended.** first
88b0: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f then the size o
88c0: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 f the file is ex
88d0: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 tended, never th
88e0: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 e other.** way a
88f0: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 round. The SQLI
8900: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 TE_IOCAP_SEQUENT
8910: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 IAL property mea
8920: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 ns that.** infor
8930: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 mation is writte
8940: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 n to disk in the
8950: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 same order as c
8960: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 alls.** to xWrit
8970: 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 e(). The SQLITE
8980: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 _IOCAP_POWERSAFE
8990: 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 _OVERWRITE prope
89a0: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a rty means that.*
89b0: 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 * after reboot f
89c0: 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 ollowing a crash
89d0: 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 or power loss,
89e0: 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 the only bytes i
89f0: 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 n a.** file that
8a00: 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 were written at
8a10: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
8a20: 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 level might hav
8a30: 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 e changed.** and
8a40: 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 that adjacent b
8a50: 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 ytes, even bytes
8a60: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 within the same
8a70: 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 sector are.** g
8a80: 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 uaranteed to be
8a90: 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 unchanged. The
8aa0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 SQLITE_IOCAP_UND
8ab0: 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 ELETABLE_WHEN_OP
8ac0: 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 EN.** flag indic
8ad0: 61 74 65 20 74 68 61 74 20 61 20 66 69 6c 65 20 ate that a file
8ae0: 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 cannot be delete
8af0: 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 d when open. Th
8b00: 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 e.** SQLITE_IOCA
8b10: 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 P_IMMUTABLE flag
8b20: 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 indicates that
8b30: 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a the file is on.*
8b40: 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 * read-only medi
8b50: 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 a and cannot be
8b60: 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20 changed even by
8b70: 70 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a processes with.*
8b80: 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69 76 69 * elevated privi
8b90: 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e leges..*/.#defin
8ba0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
8bb0: 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 TOMIC
8bc0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0x00000001
8bd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
8be0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 IOCAP_ATOMIC512
8bf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 0x0
8c00: 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 0000002.#define
8c10: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
8c20: 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 MIC1K
8c30: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 0x00000004.#
8c40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
8c50: 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 CAP_ATOMIC2K
8c60: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
8c70: 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 00008.#define SQ
8c80: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
8c90: 43 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 C4K
8ca0: 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 0x00000010.#de
8cb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
8cc0: 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 P_ATOMIC8K
8cd0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
8ce0: 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 020.#define SQLI
8cf0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 TE_IOCAP_ATOMIC1
8d00: 36 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 6K
8d10: 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 0x00000040.#defi
8d20: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
8d30: 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 ATOMIC32K
8d40: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 0x0000008
8d50: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
8d60: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b _IOCAP_ATOMIC64K
8d70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 0x
8d80: 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 00000100.#define
8d90: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 SQLITE_IOCAP_SA
8da0: 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 FE_APPEND
8db0: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 0x00000200.
8dc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
8dd0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 OCAP_SEQUENTIAL
8de0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
8df0: 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 000400.#define S
8e00: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 QLITE_IOCAP_UNDE
8e10: 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 LETABLE_WHEN_OPE
8e20: 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 N 0x00000800.#d
8e30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
8e40: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 AP_POWERSAFE_OVE
8e50: 52 57 52 49 54 45 20 20 20 20 30 78 30 30 30 30 RWRITE 0x0000
8e60: 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 1000.#define SQL
8e70: 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 ITE_IOCAP_IMMUTA
8e80: 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20 BLE
8e90: 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f 2a 0a 0x00002000../*.
8ea0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c ** CAPI3REF: Fil
8eb0: 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 e Locking Levels
8ec0: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 .**.** SQLite us
8ed0: 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 es one of these
8ee0: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 integer values a
8ef0: 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 s the second.**
8f00: 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c argument to call
8f10: 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 s it makes to th
8f20: 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 e xLock() and xU
8f30: 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a nlock() methods.
8f40: 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 ** of an [sqlite
8f50: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 3_io_methods] ob
8f60: 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 ject..*/.#define
8f70: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e SQLITE_LOCK_NON
8f80: 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 E 0.#de
8f90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b fine SQLITE_LOCK
8fa0: 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 _SHARED 1
8fb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
8fc0: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 LOCK_RESERVED
8fd0: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 2.#define SQL
8fe0: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 ITE_LOCK_PENDING
8ff0: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 3.#define
9000: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 SQLITE_LOCK_EXC
9010: 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a LUSIVE 4../*
9020: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 .** CAPI3REF: Sy
9030: 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 nchronization Ty
9040: 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 pe Flags.**.** W
9050: 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b hen SQLite invok
9060: 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d es the xSync() m
9070: 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b ethod of an.** [
9080: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
9090: 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 ds] object it us
90a0: 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e es a combination
90b0: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 of.** these int
90c0: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 eger values as t
90d0: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
90e0: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 nt..**.** When t
90f0: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 he SQLITE_SYNC_D
9100: 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 ATAONLY flag is
9110: 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 used, it means t
9120: 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 hat the.** sync
9130: 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e operation only n
9140: 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 eeds to flush da
9150: 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 ta to mass stora
9160: 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e ge. Inode.** in
9170: 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e formation need n
9180: 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 ot be flushed. I
9190: 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 f the lower four
91a0: 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 bits of the fla
91b0: 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 g.** equal SQLIT
91c0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 E_SYNC_NORMAL, t
91d0: 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 hat means to use
91e0: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 normal fsync()
91f0: 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 semantics..** If
9200: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 the lower four
9210: 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 bits equal SQLIT
9220: 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 E_SYNC_FULL, tha
9230: 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 t means.** to us
9240: 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 e Mac OS X style
9250: 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 fullsync instea
9260: 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a d of fsync()..**
9270: 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 .** Do not confu
9280: 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 se the SQLITE_SY
9290: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 NC_NORMAL and SQ
92a0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 LITE_SYNC_FULL f
92b0: 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 lags.** with the
92c0: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f [PRAGMA synchro
92d0: 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 nous]=NORMAL and
92e0: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f [PRAGMA synchro
92f0: 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 nous]=FULL.** se
9300: 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 ttings. The [sy
9310: 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 nchronous pragma
9320: 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 ] determines whe
9330: 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a n calls to the.*
9340: 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 * xSync VFS meth
9350: 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 od occur and app
9360: 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 lies uniformly a
9370: 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f cross all platfo
9380: 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 rms..** The SQLI
9390: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 TE_SYNC_NORMAL a
93a0: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 nd SQLITE_SYNC_F
93b0: 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d ULL flags determ
93c0: 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 ine how.** energ
93d0: 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 etic or rigorous
93e0: 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 or forceful the
93f0: 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 sync operations
9400: 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 are and.** only
9410: 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e make a differen
9420: 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f ce on Mac OSX fo
9430: 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 r the default SQ
9440: 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 Lite code..** (T
9450: 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 hird-party VFS i
9460: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d mplementations m
9470: 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 ight also make t
9480: 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a he distinction.*
9490: 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 * between SQLITE
94a0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 _SYNC_NORMAL and
94b0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c SQLITE_SYNC_FUL
94c0: 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 L, but among the
94d0: 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 .** operating sy
94e0: 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 stems natively s
94f0: 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 upported by SQLi
9500: 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 te, only Mac OSX
9510: 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 .** cares about
9520: 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 the difference.)
9530: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
9540: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 TE_SYNC_NORMAL
9550: 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 0x00002.#d
9560: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e efine SQLITE_SYN
9570: 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 C_FULL
9580: 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 0x00003.#define
9590: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 SQLITE_SYNC_DATA
95a0: 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 ONLY 0x0001
95b0: 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 0../*.** CAPI3RE
95c0: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 F: OS Interface
95d0: 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 Open File Handle
95e0: 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 .**.** An [sqlit
95f0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 e3_file] object
9600: 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 represents an op
9610: 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a en file in the .
9620: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 ** [sqlite3_vfs
9630: 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c | OS interface l
9640: 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 ayer]. Individu
9650: 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a al OS interface.
9660: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
9670: 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 ns will.** want
9680: 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 to subclass this
9690: 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e object by appen
96a0: 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 ding additional
96b0: 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 fields.** for th
96c0: 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 eir own use. Th
96d0: 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 e pMethods entry
96e0: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
96f0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f an.** [sqlite3_
9700: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 io_methods] obje
9710: 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 ct that defines
9720: 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 methods for perf
9730: 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 orming.** I/O op
9740: 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 erations on the
9750: 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 open file..*/.ty
9760: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
9770: 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 ite3_file sqlite
9780: 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 3_file;.struct s
9790: 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 qlite3_file {.
97a0: 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c const struct sql
97b0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 ite3_io_methods
97c0: 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d *pMethods; /* M
97d0: 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 ethods for an op
97e0: 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f en file */.};../
97f0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
9800: 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 S Interface File
9810: 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 Virtual Methods
9820: 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 Object.**.** Ev
9830: 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 ery file opened
9840: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f by the [sqlite3_
9850: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f vfs.xOpen] metho
9860: 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a d populates an.*
9870: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d * [sqlite3_file]
9880: 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 object (or, mor
9890: 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 e commonly, a su
98a0: 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a bclass of the.**
98b0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 [sqlite3_file]
98c0: 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 object) with a p
98d0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 ointer to an ins
98e0: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 tance of this ob
98f0: 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 ject..** This ob
9900: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 ject defines the
9910: 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f methods used to
9920: 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 perform various
9930: 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 operations.** a
9940: 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 gainst the open
9950: 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 file represented
9960: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 by the [sqlite3
9970: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a _file] object..*
9980: 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c *.** If the [sql
9990: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 ite3_vfs.xOpen]
99a0: 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 method sets the
99b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 sqlite3_file.pMe
99c0: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a thods element .*
99d0: 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 * to a non-NULL
99e0: 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 pointer, then th
99f0: 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 e sqlite3_io_met
9a00: 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 hods.xClose meth
9a10: 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 od.** may be inv
9a20: 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 oked even if the
9a30: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f [sqlite3_vfs.xO
9a40: 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68 pen] reported th
9a50: 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 at it failed. T
9a60: 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 he.** only way t
9a70: 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c o prevent a call
9a80: 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f to xClose follo
9a90: 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73 wing a failed [s
9aa0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e qlite3_vfs.xOpen
9ab0: 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 ].** is for the
9ac0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 [sqlite3_vfs.xOp
9ad0: 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73 en] to set the s
9ae0: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 qlite3_file.pMet
9af0: 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 hods element.**
9b00: 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 to NULL..**.** T
9b10: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e he flags argumen
9b20: 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 t to xSync may b
9b30: 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 e one of [SQLITE
9b40: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 _SYNC_NORMAL] or
9b50: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 .** [SQLITE_SYNC
9b60: 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 _FULL]. The fir
9b70: 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 st choice is the
9b80: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e normal fsync().
9b90: 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 .** The second c
9ba0: 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f hoice is a Mac O
9bb0: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 S X style fullsy
9bc0: 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 nc. The [SQLITE
9bd0: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a _SYNC_DATAONLY].
9be0: 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f ** flag may be O
9bf0: 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 Red in to indica
9c00: 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 te that only the
9c10: 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c data of the fil
9c20: 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 e.** and not its
9c30: 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 inode needs to
9c40: 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a be synced..**.**
9c50: 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c The integer val
9c60: 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 ues to xLock() a
9c70: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 nd xUnlock() are
9c80: 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a one of.** <ul>.
9c90: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
9ca0: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c LOCK_NONE],.** <
9cb0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b li> [SQLITE_LOCK
9cc0: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 _SHARED],.** <li
9cd0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 > [SQLITE_LOCK_R
9ce0: 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 ESERVED],.** <li
9cf0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 > [SQLITE_LOCK_P
9d00: 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c ENDING], or.** <
9d10: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b li> [SQLITE_LOCK
9d20: 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 _EXCLUSIVE]..**
9d30: 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 </ul>.** xLock()
9d40: 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c increases the l
9d50: 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 ock. xUnlock() d
9d60: 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 ecreases the loc
9d70: 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b k..** The xCheck
9d80: 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d ReservedLock() m
9d90: 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 ethod checks whe
9da0: 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 ther any databas
9db0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a e connection,.**
9dc0: 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 either in this
9dd0: 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f process or in so
9de0: 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 me other process
9df0: 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 , is holding a R
9e00: 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 ESERVED,.** PEND
9e10: 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 ING, or EXCLUSIV
9e20: 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 E lock on the fi
9e30: 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 le. It returns
9e40: 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 true.** if such
9e50: 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e a lock exists an
9e60: 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 d false otherwis
9e70: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 e..**.** The xFi
9e80: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 leControl() meth
9e90: 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 od is a generic
9ea0: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 interface that a
9eb0: 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 llows custom.**
9ec0: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 VFS implementati
9ed0: 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 ons to directly
9ee0: 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 control an open
9ef0: 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a file using the.*
9f00: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f * [sqlite3_file_
9f10: 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 control()] inter
9f20: 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e face. The secon
9f30: 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 d "op" argument
9f40: 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 is an.** integer
9f50: 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 opcode. The th
9f60: 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ird argument is
9f70: 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 a generic pointe
9f80: 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a r intended to.**
9f90: 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 point to a stru
9fa0: 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 cture that may c
9fb0: 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 ontain arguments
9fc0: 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 or space in whi
9fd0: 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 ch to.** write r
9fe0: 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 eturn values. P
9ff0: 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f otential uses fo
a000: 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 r xFileControl()
a010: 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e might be.** fun
a020: 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 ctions to enable
a030: 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 blocking locks
a040: 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 with timeouts, t
a050: 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 o change the.**
a060: 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 locking strategy
a070: 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f (for example to
a080: 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f use dot-file lo
a090: 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 cks), to inquire
a0a0: 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 .** about the st
a0b0: 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 atus of a lock,
a0c0: 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c or to break stal
a0d0: 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 e locks. The SQ
a0e0: 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 Lite.** core res
a0f0: 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 erves all opcode
a100: 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 s less than 100
a110: 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e for its own use.
a120: 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74 .** A [file cont
a130: 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69 rol opcodes | li
a140: 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c st of opcodes] l
a150: 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 ess than 100 is
a160: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 available..** Ap
a170: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 plications that
a180: 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 define a custom
a190: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 xFileControl met
a1a0: 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f hod should use o
a1b0: 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 pcodes.** greate
a1c0: 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 r than 100 to av
a1d0: 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 oid conflicts.
a1e0: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 VFS implementati
a1f0: 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 ons should.** re
a200: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 turn [SQLITE_NOT
a210: 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 FOUND] for file
a220: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 control opcodes
a230: 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 that they do not
a240: 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a .** recognize..*
a250: 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 *.** The xSector
a260: 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 Size() method re
a270: 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 turns the sector
a280: 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 size of the.**
a290: 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 device that unde
a2a0: 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 rlies the file.
a2b0: 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 The sector size
a2c0: 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d is the.** minim
a2d0: 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 um write that ca
a2e0: 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 n be performed w
a2f0: 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e ithout disturbin
a300: 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 g.** other bytes
a310: 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 in the file. T
a320: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 he xDeviceCharac
a330: 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d teristics().** m
a340: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 ethod returns a
a350: 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 bit vector descr
a360: 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 ibing behaviors
a370: 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c of the.** underl
a380: 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a ying device:.**.
a390: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ul>.** <li>
a3a0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 [SQLITE_IOCAP_AT
a3b0: 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 OMIC].** <li> [S
a3c0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
a3d0: 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b IC512].** <li> [
a3e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
a3f0: 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b MIC1K].** <li> [
a400: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
a410: 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b MIC2K].** <li> [
a420: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
a430: 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b MIC4K].** <li> [
a440: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
a450: 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b MIC8K].** <li> [
a460: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
a470: 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 MIC16K].** <li>
a480: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 [SQLITE_IOCAP_AT
a490: 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e OMIC32K].** <li>
a4a0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
a4b0: 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 TOMIC64K].** <li
a4c0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
a4d0: 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 SAFE_APPEND].**
a4e0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
a4f0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a AP_SEQUENTIAL].*
a500: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 * </ul>.**.** Th
a510: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
a520: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d TOMIC property m
a530: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 eans that all wr
a540: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 ites of.** any s
a550: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 ize are atomic.
a560: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
a570: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 P_ATOMICnnn valu
a580: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 es.** mean that
a590: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 writes of blocks
a5a0: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 that are nnn by
a5b0: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a tes in size and.
a5c0: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 ** are aligned t
a5d0: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 o an address whi
a5e0: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 ch is an integer
a5f0: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 multiple of.**
a600: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 nnn are atomic.
a610: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
a620: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 P_SAFE_APPEND va
a630: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 lue means.** tha
a640: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 t when data is a
a650: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c ppended to a fil
a660: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 e, the data is a
a670: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 ppended.** first
a680: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f then the size o
a690: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 f the file is ex
a6a0: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 tended, never th
a6b0: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 e other.** way a
a6c0: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 round. The SQLI
a6d0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 TE_IOCAP_SEQUENT
a6e0: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 IAL property mea
a6f0: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 ns that.** infor
a700: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 mation is writte
a710: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 n to disk in the
a720: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 same order as c
a730: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 alls.** to xWrit
a740: 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 e()..**.** If xR
a750: 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 ead() returns SQ
a760: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 LITE_IOERR_SHORT
a770: 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c _READ it must al
a780: 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 so fill.** in th
a790: 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e e unread portion
a7a0: 73 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 s of the buffer
a7b0: 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 with zeros. A V
a7c0: 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 FS that.** fails
a7d0: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 to zero-fill sh
a7e0: 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 ort reads might
a7f0: 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 seem to work. H
a800: 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 owever,.** failu
a810: 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 re to zero-fill
a820: 73 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c short reads will
a830: 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 eventually lead
a840: 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 to.** database
a850: 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 corruption..*/.t
a860: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
a870: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
a880: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 sqlite3_io_meth
a890: 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 ods;.struct sqli
a8a0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b te3_io_methods {
a8b0: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b . int iVersion;
a8c0: 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 . int (*xClose)
a8d0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b (sqlite3_file*);
a8e0: 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 . int (*xRead)(
a8f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 sqlite3_file*, v
a900: 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 oid*, int iAmt,
a910: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f sqlite3_int64 iO
a920: 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 fst);. int (*xW
a930: 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 rite)(sqlite3_fi
a940: 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a le*, const void*
a950: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 , int iAmt, sqli
a960: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 te3_int64 iOfst)
a970: 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 ;. int (*xTrunc
a980: 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ate)(sqlite3_fil
a990: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 e*, sqlite3_int6
a9a0: 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 4 size);. int (
a9b0: 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f *xSync)(sqlite3_
a9c0: 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 file*, int flags
a9d0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 );. int (*xFile
a9e0: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 Size)(sqlite3_fi
a9f0: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 le*, sqlite3_int
aa00: 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 64 *pSize);. in
aa10: 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 t (*xLock)(sqlit
aa20: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a e3_file*, int);.
aa30: 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 int (*xUnlock)
aa40: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
aa50: 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 int);. int (*xC
aa60: 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b heckReservedLock
aa70: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
aa80: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a int *pResOut);.
aa90: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e int (*xFileCon
aaa0: 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 trol)(sqlite3_fi
aab0: 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 le*, int op, voi
aac0: 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 d *pArg);. int
aad0: 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 (*xSectorSize)(s
aae0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 qlite3_file*);.
aaf0: 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 int (*xDeviceCh
ab00: 61 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73 aracteristics)(s
ab10: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 qlite3_file*);.
ab20: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 /* Methods abov
ab30: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 e are valid for
ab40: 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 version 1 */. i
ab50: 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 nt (*xShmMap)(sq
ab60: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 lite3_file*, int
ab70: 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 iPg, int pgsz,
ab80: 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 int, void volati
ab90: 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 le**);. int (*x
aba0: 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 ShmLock)(sqlite3
abb0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 _file*, int offs
abc0: 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 et, int n, int f
abd0: 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a lags);. void (*
abe0: 78 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c xShmBarrier)(sql
abf0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 ite3_file*);. i
ac00: 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 nt (*xShmUnmap)(
ac10: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 sqlite3_file*, i
ac20: 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a nt deleteFlag);.
ac30: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f /* Methods abo
ac40: 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 ve are valid for
ac50: 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 version 2 */.
ac60: 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28 73 71 int (*xFetch)(sq
ac70: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c lite3_file*, sql
ac80: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 ite3_int64 iOfst
ac90: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64 , int iAmt, void
aca0: 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28 2a **pp);. int (*
acb0: 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69 74 65 xUnfetch)(sqlite
acc0: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 3_file*, sqlite3
acd0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 76 6f _int64 iOfst, vo
ace0: 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 id *p);. /* Met
acf0: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 hods above are v
ad00: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e alid for version
ad10: 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 3 */. /* Addit
ad20: 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 ional methods ma
ad30: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 y be added in fu
ad40: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f ture releases */
ad50: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .};../*.** CAPI3
ad60: 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 REF: Standard Fi
ad70: 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 le Control Opcod
ad80: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 es.** KEYWORDS:
ad90: 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 {file control op
ada0: 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63 6f 6e codes} {file con
adb0: 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a 2a 0a trol opcode}.**.
adc0: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 ** These integer
add0: 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f constants are o
ade0: 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 pcodes for the x
adf0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 FileControl meth
ae00: 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 od.** of the [sq
ae10: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
ae20: 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 ] object and for
ae30: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 the [sqlite3_fi
ae40: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a le_control()].**
ae50: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a interface..**.*
ae60: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b * <ul>.** <li>[[
ae70: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 SQLITE_FCNTL_LOC
ae80: 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 KSTATE]].** The
ae90: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f [SQLITE_FCNTL_LO
aea0: 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 CKSTATE] opcode
aeb0: 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 is used for debu
aec0: 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 gging. This.**
aed0: 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 opcode causes th
aee0: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d e xFileControl m
aef0: 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 ethod to write t
af00: 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 he current state
af10: 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 of.** the lock
af20: 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f (one of [SQLITE_
af30: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c LOCK_NONE], [SQL
af40: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d ITE_LOCK_SHARED]
af50: 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 ,.** [SQLITE_LOC
af60: 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 K_RESERVED], [SQ
af70: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e LITE_LOCK_PENDIN
af80: 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c G], or [SQLITE_L
af90: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a OCK_EXCLUSIVE]).
afa0: 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 ** into an integ
afb0: 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72 67 er that the pArg
afc0: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 argument points
afd0: 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 to. This capabi
afe0: 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 lity.** is used
aff0: 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 during testing a
b000: 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c nd is only avail
b010: 61 62 6c 65 20 77 68 65 6e 20 74 68 65 20 53 51 able when the SQ
b020: 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63 6f 6d LITE_TEST.** com
b030: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
b040: 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 is used..**.**
b050: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
b060: 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a TL_SIZE_HINT]].*
b070: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 * The [SQLITE_FC
b080: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f NTL_SIZE_HINT] o
b090: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 62 79 pcode is used by
b0a0: 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76 65 20 SQLite to give
b0b0: 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 the VFS.** layer
b0c0: 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c a hint of how l
b0d0: 61 72 67 65 20 74 68 65 20 64 61 74 61 62 61 73 arge the databas
b0e0: 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 e file will grow
b0f0: 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20 74 68 to be during th
b100: 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 72 61 e.** current tra
b110: 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 nsaction. This
b120: 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 61 72 hint is not guar
b130: 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61 63 63 anteed to be acc
b140: 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 urate but it.**
b150: 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 is often close.
b160: 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 The underlying
b170: 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 VFS might choose
b180: 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 to preallocate
b190: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 database.** file
b1a0: 20 73 70 61 63 65 20 62 61 73 65 64 20 6f 6e 20 space based on
b1b0: 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 this hint in ord
b1c0: 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69 74 65 er to help write
b1d0: 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 s to the databas
b1e0: 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 e.** file run fa
b1f0: 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e ster..**.** <li>
b200: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 [[SQLITE_FCNTL_C
b210: 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 HUNK_SIZE]].** T
b220: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
b230: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 _CHUNK_SIZE] opc
b240: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 ode is used to r
b250: 65 71 75 65 73 74 20 74 68 61 74 20 74 68 65 20 equest that the
b260: 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 VFS.** extends a
b270: 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74 68 65 nd truncates the
b280: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 database file i
b290: 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 n chunks of a si
b2a0: 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 ze specified.**
b2b0: 62 79 20 74 68 65 20 75 73 65 72 2e 20 54 68 65 by the user. The
b2c0: 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 fourth argument
b2d0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c to [sqlite3_fil
b2e0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f e_control()] sho
b2f0: 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f uld .** point to
b300: 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70 an integer (typ
b310: 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e e int) containin
b320: 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d g the new chunk-
b330: 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 size to use.** f
b340: 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 or the nominated
b350: 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 database. Alloc
b360: 61 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 66 ating database f
b370: 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72 ile space in lar
b380: 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 ge.** chunks (sa
b390: 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29 y 1MB at a time)
b3a0: 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c , may reduce fil
b3b0: 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e e-system fragmen
b3c0: 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d tation and.** im
b3d0: 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 prove performanc
b3e0: 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d e on some system
b3f0: 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 s..**.** <li>[[S
b400: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 QLITE_FCNTL_FILE
b410: 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 _POINTER]].** Th
b420: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
b430: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 FILE_POINTER] op
b440: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 code is used to
b450: 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 obtain a pointer
b460: 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 .** to the [sqli
b470: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 te3_file] object
b480: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
b490: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 a particular da
b4a0: 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 tabase.** connec
b4b0: 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 tion. See also
b4c0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f [SQLITE_FCNTL_JO
b4d0: 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 2e 0a URNAL_POINTER]..
b4e0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
b4f0: 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c TE_FCNTL_JOURNAL
b500: 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 _POINTER]].** Th
b510: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
b520: 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d JOURNAL_POINTER]
b530: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 opcode is used
b540: 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e to obtain a poin
b550: 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 ter.** to the [s
b560: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a qlite3_file] obj
b570: 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 ect associated w
b580: 69 74 68 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 ith the journal
b590: 66 69 6c 65 20 28 65 69 74 68 65 72 0a 2a 2a 20 file (either.**
b5a0: 74 68 65 20 5b 72 6f 6c 6c 62 61 63 6b 20 6a 6f the [rollback jo
b5b0: 75 72 6e 61 6c 5d 20 6f 72 20 74 68 65 20 5b 77 urnal] or the [w
b5c0: 72 69 74 65 2d 61 68 65 61 64 20 6c 6f 67 5d 29 rite-ahead log])
b5d0: 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 for a particula
b5e0: 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f r database.** co
b5f0: 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 nnection. See a
b600: 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 lso [SQLITE_FCNT
b610: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 2e L_FILE_POINTER].
b620: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
b630: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f ITE_FCNTL_SYNC_O
b640: 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c MITTED]].** No l
b650: 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a onger in use..**
b660: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
b670: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a _FCNTL_SYNC]].**
b680: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e The [SQLITE_FCN
b690: 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20 TL_SYNC] opcode
b6a0: 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 is generated int
b6b0: 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 ernally by SQLit
b6c0: 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f e and.** sent to
b6d0: 20 74 68 65 20 56 46 53 20 69 6d 6d 65 64 69 61 the VFS immedia
b6e0: 74 65 6c 79 20 62 65 66 6f 72 65 20 74 68 65 20 tely before the
b6f0: 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 xSync method is
b700: 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 invoked on a.**
b710: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 64 65 database file de
b720: 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66 scriptor. Or, if
b730: 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f the xSync metho
b740: 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 d is not invoked
b750: 20 0a 2a 2a 20 62 65 63 61 75 73 65 20 74 68 65 .** because the
b760: 20 75 73 65 72 20 68 61 73 20 63 6f 6e 66 69 67 user has config
b770: 75 72 65 64 20 53 51 4c 69 74 65 20 77 69 74 68 ured SQLite with
b780: 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e .** [PRAGMA syn
b790: 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d chronous | PRAGM
b7a0: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 A synchronous=OF
b7b0: 46 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 F] it is invoked
b7c0: 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 in place .** of
b7d0: 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f the xSync metho
b7e0: 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73 65 73 d. In most cases
b7f0: 2c 20 74 68 65 20 70 6f 69 6e 74 65 72 20 61 72 , the pointer ar
b800: 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 77 69 gument passed wi
b810: 74 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d th.** this file-
b820: 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e control is NULL.
b830: 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68 65 However, if the
b840: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 database file i
b850: 73 20 62 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a s being synced.*
b860: 2a 20 61 73 20 70 61 72 74 20 6f 66 20 61 20 6d * as part of a m
b870: 75 6c 74 69 2d 64 61 74 61 62 61 73 65 20 63 6f ulti-database co
b880: 6d 6d 69 74 2c 20 74 68 65 20 61 72 67 75 6d 65 mmit, the argume
b890: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e nt points to a n
b8a0: 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a ul-terminated.**
b8b0: 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 string containi
b8c0: 6e 67 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 ng the transacti
b8d0: 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e ons master-journ
b8e0: 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46 al file name. VF
b8f0: 53 65 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20 Ses that .** do
b900: 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 not need this si
b910: 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65 gnal should sile
b920: 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 ntly ignore this
b930: 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 opcode. Applica
b940: 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 tions .** should
b950: 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 not call [sqlit
b960: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 e3_file_control(
b970: 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 )] with this opc
b980: 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 ode as doing so
b990: 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75 70 74 20 may .** disrupt
b9a0: 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 the operation of
b9b0: 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 the specialized
b9c0: 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 VFSes that do r
b9d0: 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a equire it. .**.
b9e0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
b9f0: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 FCNTL_COMMIT_PHA
ba00: 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b SETWO]].** The [
ba10: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d SQLITE_FCNTL_COM
ba20: 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70 MIT_PHASETWO] op
ba30: 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 code is generate
ba40: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 d internally by
ba50: 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65 SQLite.** and se
ba60: 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 61 66 nt to the VFS af
ba70: 74 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f ter a transactio
ba80: 6e 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69 n has been commi
ba90: 74 74 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 tted immediately
baa0: 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72 65 20 74 .** but before t
bab0: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 75 he database is u
bac0: 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73 20 74 nlocked. VFSes t
bad0: 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 hat do not need
bae0: 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 this signal.** s
baf0: 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 hould silently i
bb00: 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 gnore this opcod
bb10: 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 e. Applications
bb20: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a should not call.
bb30: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 ** [sqlite3_file
bb40: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 _control()] with
bb50: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 this opcode as
bb60: 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 doing so may dis
bb70: 72 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65 rupt the .** ope
bb80: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 ration of the sp
bb90: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 ecialized VFSes
bba0: 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 that do require
bbb0: 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e it. .**.** <li>
bbc0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 [[SQLITE_FCNTL_W
bbd0: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a IN32_AV_RETRY]].
bbe0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f ** ^The [SQLITE_
bbf0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 FCNTL_WIN32_AV_R
bc00: 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 ETRY] opcode is
bc10: 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 used to configur
bc20: 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 e automatic.** r
bc30: 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 etry counts and
bc40: 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 intervals for ce
bc50: 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f rtain disk I/O o
bc60: 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 perations for th
bc70: 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 e.** windows [VF
bc80: 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 S] in order to p
bc90: 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 rovide robustnes
bca0: 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63 s in the presenc
bcb0: 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 e of.** anti-vir
bcc0: 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 us programs. By
bcd0: 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 default, the wi
bce0: 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 ndows VFS will r
bcf0: 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a etry file read,.
bd00: 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 ** file write, a
bd10: 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f nd file delete o
bd20: 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 perations up to
bd30: 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61 10 times, with a
bd40: 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 delay.** of 25
bd50: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 milliseconds bef
bd60: 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 72 65 ore the first re
bd70: 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 68 65 try and with the
bd80: 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e delay increasin
bd90: 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74 g.** by an addit
bda0: 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 ional 25 millise
bdb0: 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68 20 conds with each
bdc0: 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 72 79 subsequent retry
bdd0: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 . This.** opcod
bde0: 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 e allows these t
bdf0: 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72 65 wo values (10 re
be00: 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c tries and 25 mil
be10: 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c liseconds of del
be20: 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a ay).** to be adj
be30: 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75 usted. The valu
be40: 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 20 66 es are changed f
be50: 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 or all database
be60: 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 connections.** w
be70: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 ithin the same p
be80: 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72 67 rocess. The arg
be90: 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 ument is a point
bea0: 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f er to an array o
beb0: 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 f two.** integer
bec0: 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73 s where the firs
bed0: 74 20 69 6e 74 65 67 65 72 20 69 20 74 68 65 20 t integer i the
bee0: 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20 new retry count
bef0: 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a and the second.*
bf00: 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 * integer is the
bf10: 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68 delay. If eith
bf20: 65 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65 er integer is ne
bf30: 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 gative, then the
bf40: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e setting.** is n
bf50: 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 69 ot changed but i
bf60: 6e 73 74 65 61 64 20 74 68 65 20 70 72 69 6f 72 nstead the prior
bf70: 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73 value of that s
bf80: 65 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 65 etting is writte
bf90: 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 n.** into the ar
bfa0: 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 ray entry, allow
bfb0: 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 20 ing the current
bfc0: 72 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 74 retry settings t
bfd0: 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 o be.** interrog
bfe0: 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 ated. The zDbNa
bff0: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 me parameter is
c000: 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c ignored..**.** <
c010: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
c020: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a L_PERSIST_WAL]].
c030: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f ** ^The [SQLITE_
c040: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 FCNTL_PERSIST_WA
c050: 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 L] opcode is use
c060: 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 d to set or quer
c070: 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 y the.** persist
c080: 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 ent [WAL | Write
c090: 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 Ahead Log] sett
c0a0: 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 ing. By default
c0b0: 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a , the auxiliary.
c0c0: 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 6c ** write ahead l
c0d0: 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 og and shared me
c0e0: 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64 20 mory files used
c0f0: 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 for transaction
c100: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 control.** are a
c110: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c utomatically del
c120: 65 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 eted when the la
c130: 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 test connection
c140: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a to the database.
c150: 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 ** closes. Sett
c160: 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 ing persistent W
c170: 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 AL mode causes t
c180: 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 hose files to pe
c190: 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 rsist after.** c
c1a0: 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e lose. Persistin
c1b0: 67 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 g the files is u
c1c0: 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 seful when other
c1d0: 20 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 processes that
c1e0: 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 do not.** have w
c1f0: 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 rite permission
c200: 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 on the directory
c210: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 containing the
c220: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 database file wa
c230: 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 nt.** to read th
c240: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c e database file,
c250: 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 as the WAL and
c260: 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 shared memory fi
c270: 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a les must exist.*
c280: 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 * in order for t
c290: 68 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 he database to b
c2a0: 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 e readable. The
c2b0: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
c2c0: 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 r to.** [sqlite3
c2d0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d _file_control()]
c2e0: 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 for this opcode
c2f0: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 should be a poi
c300: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 nter to an integ
c310: 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 er..** That inte
c320: 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 ger is 0 to disa
c330: 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 ble persistent W
c340: 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 AL mode or 1 to
c350: 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e enable persisten
c360: 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 t.** WAL mode.
c370: 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 If the integer i
c380: 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 s -1, then it is
c390: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 overwritten wit
c3a0: 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a h the current.**
c3b0: 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 WAL persistence
c3c0: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 setting..**.**
c3d0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
c3e0: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 TL_POWERSAFE_OVE
c3f0: 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 RWRITE]].** ^The
c400: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 [SQLITE_FCNTL_P
c410: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 OWERSAFE_OVERWRI
c420: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 TE] opcode is us
c430: 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 ed to set or que
c440: 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 ry the.** persis
c450: 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d tent "powersafe-
c460: 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 50 overwrite" or "P
c470: 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54 SOW" setting. T
c480: 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a he PSOW setting.
c490: 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 ** determines th
c4a0: 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f e [SQLITE_IOCAP_
c4b0: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 POWERSAFE_OVERWR
c4c0: 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a ITE] bit of the.
c4d0: 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 63 ** xDeviceCharac
c4e0: 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 teristics method
c4f0: 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 s. The fourth pa
c500: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 rameter to.** [s
c510: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 qlite3_file_cont
c520: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 rol()] for this
c530: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 opcode should be
c540: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
c550: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 integer..** Tha
c560: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 t integer is 0 t
c570: 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 o disable zero-d
c580: 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 amage mode or 1
c590: 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 to enable zero-d
c5a0: 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 amage.** mode.
c5b0: 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 If the integer i
c5c0: 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 s -1, then it is
c5d0: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 overwritten wit
c5e0: 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a h the current.**
c5f0: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 zero-damage mod
c600: 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a e setting..**.**
c610: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
c620: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a NTL_OVERWRITE]].
c630: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f ** ^The [SQLITE_
c640: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d FCNTL_OVERWRITE]
c650: 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b opcode is invok
c660: 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 ed by SQLite aft
c670: 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 er opening.** a
c680: 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f write transactio
c690: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 n to indicate th
c6a0: 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 at, unless it is
c6b0: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 rolled back for
c6c0: 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c some.** reason,
c6d0: 20 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 the entire data
c6e0: 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 base file will b
c6f0: 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 e overwritten by
c700: 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a the current .**
c710: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 transaction. Th
c720: 69 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41 is is used by VA
c730: 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e CUUM operations.
c740: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
c750: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d ITE_FCNTL_VFSNAM
c760: 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c E]].** ^The [SQL
c770: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d ITE_FCNTL_VFSNAM
c780: 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 E] opcode can be
c790: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 used to obtain
c7a0: 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 the names of.**
c7b0: 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 all [VFSes] in t
c7c0: 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 he VFS stack. T
c7d0: 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 he names are of
c7e0: 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e all VFS shims an
c7f0: 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 d the.** final b
c800: 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 ottom-level VFS
c810: 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f are written into
c820: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 memory obtained
c830: 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 from .** [sqlit
c840: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 e3_malloc()] and
c850: 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 the result is s
c860: 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 tored in the cha
c870: 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 r* variable.** t
c880: 68 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 hat the fourth p
c890: 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c arameter of [sql
c8a0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
c8b0: 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a l()] points to..
c8c0: 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 ** The caller is
c8d0: 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 responsible for
c8e0: 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d freeing the mem
c8f0: 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 ory when done.
c900: 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 As with.** all f
c910: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 ile-control acti
c920: 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f ons, there is no
c930: 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 guarantee that
c940: 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c this will actual
c950: 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e ly.** do anythin
c960: 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 g. Callers shou
c970: 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 ld initialize th
c980: 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 e char* variable
c990: 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f to a NULL.** po
c9a0: 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 inter in case th
c9b0: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 is file-control
c9c0: 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 is not implement
c9d0: 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 ed. This file-c
c9e0: 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 ontrol.** is int
c9f0: 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f ended for diagno
ca00: 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a stic use only..*
ca10: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
ca20: 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e E_FCNTL_VFS_POIN
ca30: 54 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 TER]].** ^The [S
ca40: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f QLITE_FCNTL_VFS_
ca50: 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 POINTER] opcode
ca60: 66 69 6e 64 73 20 61 20 70 6f 69 6e 74 65 72 20 finds a pointer
ca70: 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c to the top-level
ca80: 0a 2a 2a 20 5b 56 46 53 65 73 5d 20 63 75 72 72 .** [VFSes] curr
ca90: 65 6e 74 6c 79 20 69 6e 20 75 73 65 2e 20 20 5e ently in use. ^
caa0: 28 54 68 65 20 61 72 67 75 6d 65 6e 74 20 58 20 (The argument X
cab0: 69 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 in.** sqlite3_fi
cac0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 64 62 2c 53 51 le_control(db,SQ
cad0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 LITE_FCNTL_VFS_P
cae0: 4f 49 4e 54 45 52 2c 58 29 20 6d 75 73 74 20 62 OINTER,X) must b
caf0: 65 0a 2a 2a 20 6f 66 20 74 79 70 65 20 22 5b 73 e.** of type "[s
cb00: 71 6c 69 74 65 33 5f 76 66 73 5d 20 2a 2a 22 2e qlite3_vfs] **".
cb10: 20 20 54 68 69 73 20 6f 70 63 6f 64 65 73 20 77 This opcodes w
cb20: 69 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a 20 74 6f ill set *X.** to
cb30: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
cb40: 65 20 74 6f 70 2d 6c 65 76 65 6c 20 56 46 53 2e e top-level VFS.
cb50: 29 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 72 )^.** ^When ther
cb60: 65 20 61 72 65 20 6d 75 6c 74 69 70 6c 65 20 56 e are multiple V
cb70: 46 53 20 73 68 69 6d 73 20 69 6e 20 74 68 65 20 FS shims in the
cb80: 73 74 61 63 6b 2c 20 74 68 69 73 20 6f 70 63 6f stack, this opco
cb90: 64 65 20 66 69 6e 64 73 20 74 68 65 0a 2a 2a 20 de finds the.**
cba0: 75 70 70 65 72 2d 6d 6f 73 74 20 73 68 69 6d 20 upper-most shim
cbb0: 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e only..**.** <li>
cbc0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 [[SQLITE_FCNTL_P
cbd0: 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e RAGMA]].** ^When
cbe0: 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 ever a [PRAGMA]
cbf0: 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 statement is par
cc00: 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f sed, an [SQLITE_
cc10: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a FCNTL_PRAGMA] .*
cc20: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 * file control i
cc30: 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 s sent to the op
cc40: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 en [sqlite3_file
cc50: 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 ] object corresp
cc60: 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 onding.** to the
cc70: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 database file t
cc80: 6f 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67 o which the prag
cc90: 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 ma statement ref
cca0: 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 ers. ^The argume
ccb0: 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 nt.** to the [SQ
ccc0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d LITE_FCNTL_PRAGM
ccd0: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 A] file control
cce0: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a is an array of.*
ccf0: 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 * pointers to st
cd00: 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 rings (char**) i
cd10: 6e 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f n which the seco
cd20: 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 nd element of th
cd30: 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 e array.** is th
cd40: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 e name of the pr
cd50: 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 agma and the thi
cd60: 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 rd element is th
cd70: 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 e argument to th
cd80: 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e e.** pragma or N
cd90: 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d ULL if the pragm
cda0: 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e a has no argumen
cdb0: 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 t. ^The handler
cdc0: 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 for an.** [SQLI
cdd0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d TE_FCNTL_PRAGMA]
cde0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 file control ca
cdf0: 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b n optionally mak
ce00: 65 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d e the first elem
ce10: 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 ent.** of the ch
ce20: 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f ar** argument po
ce30: 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 int to a string
ce40: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 obtained from [s
ce50: 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 qlite3_mprintf()
ce60: 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 ].** or the equi
ce70: 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 valent and that
ce80: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f string will beco
ce90: 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 me the result of
cea0: 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a the pragma or.*
ceb0: 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 * the error mess
cec0: 61 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d age if the pragm
ced0: 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 a fails. ^If the
cee0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 .** [SQLITE_FCNT
cef0: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 L_PRAGMA] file c
cf00: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b ontrol returns [
cf10: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d SQLITE_NOTFOUND]
cf20: 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a , then normal .*
cf30: 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 * [PRAGMA] proce
cf40: 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e ssing continues.
cf50: 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 ^If the [SQLIT
cf60: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a E_FCNTL_PRAGMA].
cf70: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 ** file control
cf80: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
cf90: 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 OK], then the pa
cfa0: 72 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 rser assumes tha
cfb0: 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 t the.** VFS has
cfc0: 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 handled the PRA
cfd0: 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 GMA itself and t
cfe0: 68 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 he parser genera
cff0: 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 tes a no-op.** p
d000: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
d010: 74 20 69 66 20 72 65 73 75 6c 74 20 73 74 72 69 t if result stri
d020: 6e 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72 20 74 ng is NULL, or t
d030: 68 61 74 20 72 65 74 75 72 6e 73 20 61 20 63 6f hat returns a co
d040: 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 py.** of the res
d050: 75 6c 74 20 73 74 72 69 6e 67 20 69 66 20 74 68 ult string if th
d060: 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 6e 2d e string is non-
d070: 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 NULL..** ^If the
d080: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 [SQLITE_FCNTL_P
d090: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 RAGMA] file cont
d0a0: 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 rol returns.** a
d0b0: 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f ny result code o
d0c0: 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 ther than [SQLIT
d0d0: 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 E_OK] or [SQLITE
d0e0: 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 _NOTFOUND], that
d0f0: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 means.** that t
d100: 68 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 he VFS encounter
d110: 65 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c ed an error whil
d120: 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b e handling the [
d130: 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a PRAGMA] and the.
d140: 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f ** compilation o
d150: 66 20 74 68 65 20 50 52 41 47 4d 41 20 66 61 69 f the PRAGMA fai
d160: 6c 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 ls with an error
d170: 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f . ^The [SQLITE_
d180: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a FCNTL_PRAGMA].**
d190: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 file control oc
d1a0: 63 75 72 73 20 61 74 20 74 68 65 20 62 65 67 69 curs at the begi
d1b0: 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 nning of pragma
d1c0: 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 statement analys
d1d0: 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 is and so.** it
d1e0: 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 is able to overr
d1f0: 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 ide built-in [PR
d200: 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 AGMA] statements
d210: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
d220: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 LITE_FCNTL_BUSYH
d230: 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 ANDLER]].** ^The
d240: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 [SQLITE_FCNTL_B
d250: 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 USYHANDLER].** f
d260: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 ile-control may
d270: 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 be invoked by SQ
d280: 4c 69 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61 Lite on the data
d290: 62 61 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 base file handle
d2a0: 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65 .** shortly afte
d2b0: 72 20 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69 r it is opened i
d2c0: 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 n order to provi
d2d0: 64 65 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20 de a custom VFS
d2e0: 77 69 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 with access.** t
d2f0: 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e o the connection
d300: 73 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 s busy-handler c
d310: 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67 allback. The arg
d320: 75 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65 ument is of type
d330: 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 (void **).** -
d340: 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20 an array of two
d350: 28 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e (void *) values.
d360: 20 54 68 65 20 66 69 72 73 74 20 28 76 6f 69 64 The first (void
d370: 20 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 *) actually poi
d380: 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 nts.** to a func
d390: 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e tion of type (in
d3a0: 74 20 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 t (*)(void *)).
d3b0: 49 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f In order to invo
d3c0: 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f ke the connectio
d3d0: 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c ns.** busy-handl
d3e0: 65 72 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f er, this functio
d3f0: 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f n should be invo
d400: 6b 65 64 20 77 69 74 68 20 74 68 65 20 73 65 63 ked with the sec
d410: 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a ond (void *) in.
d420: 2a 2a 20 74 68 65 20 61 72 72 61 79 20 61 73 20 ** the array as
d430: 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e the only argumen
d440: 74 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 t. If it returns
d450: 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 non-zero, then
d460: 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a the operation.**
d470: 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69 should be retri
d480: 65 64 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e ed. If it return
d490: 73 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74 s zero, the cust
d4a0: 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62 om VFS should ab
d4b0: 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 andon the.** cur
d4c0: 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a rent operation..
d4d0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
d4e0: 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c TE_FCNTL_TEMPFIL
d4f0: 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c ENAME]].** ^Appl
d500: 69 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f ication can invo
d510: 6b 65 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 ke the [SQLITE_F
d520: 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d CNTL_TEMPFILENAM
d530: 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a E] file-control.
d540: 2a 2a 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 ** to have SQLit
d550: 65 20 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 e generate a.**
d560: 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 temporary filena
d570: 6d 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d me using the sam
d580: 65 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 e algorithm that
d590: 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 is followed to
d5a0: 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 generate.** temp
d5b0: 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 orary filenames
d5c0: 66 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 for TEMP tables
d5d0: 61 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e and other intern
d5e0: 61 6c 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a al uses. The.**
d5f0: 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 argument should
d600: 20 62 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 be a char** whi
d610: 63 68 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 ch will be fille
d620: 64 20 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e d with the filen
d630: 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 ame.** written i
d640: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 nto memory obtai
d650: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 ned from [sqlite
d660: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 3_malloc()]. Th
d670: 65 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a e caller should.
d680: 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 ** invoke [sqlit
d690: 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 e3_free()] on th
d6a0: 65 20 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 e result to avoi
d6b0: 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e d a memory leak.
d6c0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
d6d0: 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 ITE_FCNTL_MMAP_S
d6e0: 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 IZE]].** The [SQ
d6f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f LITE_FCNTL_MMAP_
d700: 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 SIZE] file contr
d710: 6f 6c 20 69 73 20 75 73 65 64 20 74 6f 20 71 75 ol is used to qu
d720: 65 72 79 20 6f 72 20 73 65 74 20 74 68 65 0a 2a ery or set the.*
d730: 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 * maximum number
d740: 20 6f 66 20 62 79 74 65 73 20 74 68 61 74 20 77 of bytes that w
d750: 69 6c 6c 20 62 65 20 75 73 65 64 20 66 6f 72 20 ill be used for
d760: 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f memory-mapped I/
d770: 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 O..** The argume
d780: 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 nt is a pointer
d790: 74 6f 20 61 20 76 61 6c 75 65 20 6f 66 20 74 79 to a value of ty
d7a0: 70 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 pe sqlite3_int64
d7b0: 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 that.** is an a
d7c0: 64 76 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 dvisory maximum
d7d0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
d7e0: 69 6e 20 74 68 65 20 66 69 6c 65 20 74 6f 20 6d in the file to m
d7f0: 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68 65 0a emory map. The.
d800: 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 ** pointer is ov
d810: 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 erwritten with t
d820: 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 he old value. T
d830: 68 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 he limit is not
d840: 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 changed if.** th
d850: 65 20 76 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c e value original
d860: 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 ly pointed to is
d870: 20 6e 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73 negative, and s
d880: 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69 o the current li
d890: 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 mit .** can be q
d8a0: 75 65 72 69 65 64 20 62 79 20 70 61 73 73 69 6e ueried by passin
d8b0: 67 20 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 g in a pointer t
d8c0: 6f 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d o a negative num
d8d0: 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 ber. This.** fi
d8e0: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 le-control is us
d8f0: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f ed internally to
d900: 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 implement [PRAG
d910: 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a MA mmap_size]..*
d920: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
d930: 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a E_FCNTL_TRACE]].
d940: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 ** The [SQLITE_F
d950: 43 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 CNTL_TRACE] file
d960: 20 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 control provide
d970: 73 20 61 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 s advisory infor
d980: 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 mation.** to the
d990: 20 56 46 53 20 61 62 6f 75 74 20 77 68 61 74 20 VFS about what
d9a0: 74 68 65 20 68 69 67 68 65 72 20 6c 61 79 65 72 the higher layer
d9b0: 73 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 s of the SQLite
d9c0: 73 74 61 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e stack are doing.
d9d0: 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f .** This file co
d9e0: 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 62 79 ntrol is used by
d9f0: 20 73 6f 6d 65 20 56 46 53 20 61 63 74 69 76 69 some VFS activi
da00: 74 79 20 74 72 61 63 69 6e 67 20 5b 73 68 69 6d ty tracing [shim
da10: 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d s]..** The argum
da20: 65 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 ent is a zero-te
da30: 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 2e rminated string.
da40: 20 20 48 69 67 68 65 72 20 6c 61 79 65 72 73 20 Higher layers
da50: 69 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 in the.** SQLite
da60: 20 73 74 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 stack may gener
da70: 61 74 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 ate instances of
da80: 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 this file contr
da90: 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 ol if.** the [SQ
daa0: 4c 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 LITE_USE_FCNTL_T
dab0: 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 RACE] compile-ti
dac0: 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 me option is ena
dad0: 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e bled..**.** <li>
dae0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 [[SQLITE_FCNTL_H
daf0: 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 AS_MOVED]].** Th
db00: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
db10: 48 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20 HAS_MOVED] file
db20: 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 control interpre
db30: 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 ts its argument
db40: 61 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 as a.** pointer
db50: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e to an integer an
db60: 64 20 69 74 20 77 72 69 74 65 73 20 61 20 62 6f d it writes a bo
db70: 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61 74 20 olean into that
db80: 69 6e 74 65 67 65 72 20 64 65 70 65 6e 64 69 6e integer dependin
db90: 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 g.** on whether
dba0: 6f 72 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 or not the file
dbb0: 68 61 73 20 62 65 65 6e 20 72 65 6e 61 6d 65 64 has been renamed
dbc0: 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65 , moved, or dele
dbd0: 74 65 64 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20 ted since it.**
dbe0: 77 61 73 20 66 69 72 73 74 20 6f 70 65 6e 65 64 was first opened
dbf0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
dc00: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 LITE_FCNTL_WIN32
dc10: 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a _SET_HANDLE]].**
dc20: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e The [SQLITE_FCN
dc30: 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e TL_WIN32_SET_HAN
dc40: 44 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 DLE] opcode is u
dc50: 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e sed for debuggin
dc60: 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f g. This.** opco
dc70: 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 de causes the xF
dc80: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f ileControl metho
dc90: 64 20 74 6f 20 73 77 61 70 20 74 68 65 20 66 69 d to swap the fi
dca0: 6c 65 20 68 61 6e 64 6c 65 20 77 69 74 68 20 74 le handle with t
dcb0: 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 he one.** pointe
dcc0: 64 20 74 6f 20 62 79 20 74 68 65 20 70 41 72 67 d to by the pArg
dcd0: 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 69 73 argument. This
dce0: 20 63 61 70 61 62 69 6c 69 74 79 20 69 73 20 75 capability is u
dcf0: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 sed during testi
dd00: 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e ng.** and only n
dd10: 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f eeds to be suppo
dd20: 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 rted when SQLITE
dd30: 5f 54 45 53 54 20 69 73 20 64 65 66 69 6e 65 64 _TEST is defined
dd40: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
dd50: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 LITE_FCNTL_WAL_B
dd60: 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 LOCK]].** The [S
dd70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f QLITE_FCNTL_WAL_
dd80: 42 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69 67 6e BLOCK] is a sign
dd90: 61 6c 20 74 6f 20 74 68 65 20 56 46 53 20 6c 61 al to the VFS la
dda0: 79 65 72 20 74 68 61 74 20 69 74 20 6d 69 67 68 yer that it migh
ddb0: 74 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74 61 67 t.** be advantag
ddc0: 65 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e eous to block on
ddd0: 20 74 68 65 20 6e 65 78 74 20 57 41 4c 20 6c 6f the next WAL lo
dde0: 63 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b 20 69 ck if the lock i
ddf0: 73 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74 65 6c s not immediatel
de00: 79 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65 2e 20 y.** available.
de10: 20 54 68 65 20 57 41 4c 20 73 75 62 73 79 73 74 The WAL subsyst
de20: 65 6d 20 69 73 73 75 65 73 20 74 68 69 73 20 73 em issues this s
de30: 69 67 6e 61 6c 20 64 75 72 69 6e 67 20 72 61 72 ignal during rar
de40: 65 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61 6e 63 e.** circumstanc
de50: 65 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 es in order to f
de60: 69 78 20 61 20 70 72 6f 62 6c 65 6d 20 77 69 74 ix a problem wit
de70: 68 20 70 72 69 6f 72 69 74 79 20 69 6e 76 65 72 h priority inver
de80: 73 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 sion..** Applica
de90: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c 65 6d tions should <em
dea0: 3e 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20 74 68 >not</em> use th
deb0: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e is file-control.
dec0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
ded0: 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 ITE_FCNTL_ZIPVFS
dee0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 ]].** The [SQLIT
def0: 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 20 E_FCNTL_ZIPVFS]
df00: 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d opcode is implem
df10: 65 6e 74 65 64 20 62 79 20 7a 69 70 76 66 73 20 ented by zipvfs
df20: 6f 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65 72 0a only. All other.
df30: 2a 2a 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 ** VFS should re
df40: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 turn SQLITE_NOTF
df50: 4f 55 4e 44 20 66 6f 72 20 74 68 69 73 20 6f 70 OUND for this op
df60: 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e code..**.** <li>
df70: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 [[SQLITE_FCNTL_R
df80: 42 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c BU]].** The [SQL
df90: 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 20 6f ITE_FCNTL_RBU] o
dfa0: 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 pcode is impleme
dfb0: 6e 74 65 64 20 62 79 20 74 68 65 20 73 70 65 63 nted by the spec
dfc0: 69 61 6c 20 56 46 53 20 75 73 65 64 20 62 79 0a ial VFS used by.
dfd0: 2a 2a 20 74 68 65 20 52 42 55 20 65 78 74 65 6e ** the RBU exten
dfe0: 73 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 sion only. All
dff0: 6f 74 68 65 72 20 56 46 53 20 73 68 6f 75 6c 64 other VFS should
e000: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e return SQLITE_N
e010: 4f 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a 20 74 OTFOUND for.** t
e020: 68 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a his opcode. .**
e030: 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e </ul>.*/.#defin
e040: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c e SQLITE_FCNTL_L
e050: 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 OCKSTATE
e060: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 1.#define
e070: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 SQLITE_FCNTL_GE
e080: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 T_LOCKPROXYFILE
e090: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 2.#define
e0a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 SQLITE_FCNTL_SET
e0b0: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 _LOCKPROXYFILE
e0c0: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 3.#define S
e0d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 QLITE_FCNTL_LAST
e0e0: 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 _ERRNO
e0f0: 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4.#define SQ
e100: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f LITE_FCNTL_SIZE_
e110: 48 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 HINT
e120: 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 5.#define SQL
e130: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f ITE_FCNTL_CHUNK_
e140: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 SIZE
e150: 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 6.#define SQLI
e160: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f TE_FCNTL_FILE_PO
e170: 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20 INTER
e180: 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 7.#define SQLIT
e190: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 E_FCNTL_SYNC_OMI
e1a0: 54 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20 TTED
e1b0: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 8.#define SQLITE
e1c0: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f _FCNTL_WIN32_AV_
e1d0: 52 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39 RETRY 9
e1e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
e1f0: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 FCNTL_PERSIST_WA
e200: 4c 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a L 10.
e210: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
e220: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 CNTL_OVERWRITE
e230: 20 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 11.#
e240: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
e250: 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 NTL_VFSNAME
e260: 20 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 12.#d
e270: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
e280: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 TL_POWERSAFE_OVE
e290: 52 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 RWRITE 13.#de
e2a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
e2b0: 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 L_PRAGMA
e2c0: 20 20 20 20 20 20 20 20 20 31 34 0a 23 64 65 66 14.#def
e2d0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
e2e0: 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20 _BUSYHANDLER
e2f0: 20 20 20 20 20 20 20 20 31 35 0a 23 64 65 66 69 15.#defi
e300: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
e310: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 TEMPFILENAME
e320: 20 20 20 20 20 20 20 31 36 0a 23 64 65 66 69 6e 16.#defin
e330: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d e SQLITE_FCNTL_M
e340: 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20 20 MAP_SIZE
e350: 20 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e 65 18.#define
e360: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 SQLITE_FCNTL_TR
e370: 41 43 45 20 20 20 20 20 20 20 20 20 20 20 20 20 ACE
e380: 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65 20 19.#define
e390: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 SQLITE_FCNTL_HAS
e3a0: 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20 20 _MOVED
e3b0: 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20 53 20.#define S
e3c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 QLITE_FCNTL_SYNC
e3d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
e3e0: 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53 51 21.#define SQ
e3f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 LITE_FCNTL_COMMI
e400: 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20 20 T_PHASETWO
e410: 20 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 22.#define SQL
e420: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f ITE_FCNTL_WIN32_
e430: 53 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 SET_HANDLE
e440: 20 32 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 23.#define SQLI
e450: 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f TE_FCNTL_WAL_BLO
e460: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 CK
e470: 32 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 24.#define SQLIT
e480: 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 20 20 E_FCNTL_ZIPVFS
e490: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 2
e4a0: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5.#define SQLITE
e4b0: 5f 46 43 4e 54 4c 5f 52 42 55 20 20 20 20 20 20 _FCNTL_RBU
e4c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 36 26
e4d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
e4e0: 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 FCNTL_VFS_POINTE
e4f0: 52 20 20 20 20 20 20 20 20 20 20 20 20 32 37 0a R 27.
e500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
e510: 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 CNTL_JOURNAL_POI
e520: 4e 54 45 52 20 20 20 20 20 20 20 20 32 38 0a 0a NTER 28..
e530: 2f 2a 20 64 65 70 72 65 63 61 74 65 64 20 6e 61 /* deprecated na
e540: 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 mes */.#define S
e550: 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 QLITE_GET_LOCKPR
e560: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c OXYFILE SQL
e570: 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f ITE_FCNTL_GET_LO
e580: 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 CKPROXYFILE.#def
e590: 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c ine SQLITE_SET_L
e5a0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 OCKPROXYFILE
e5b0: 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 SQLITE_FCNTL_S
e5c0: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 ET_LOCKPROXYFILE
e5d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
e5e0: 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 LAST_ERRNO
e5f0: 20 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 SQLITE_FC
e600: 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a NTL_LAST_ERRNO..
e610: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
e620: 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a Mutex Handle.**
e630: 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f .** The mutex mo
e640: 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 dule within SQLi
e650: 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 te defines [sqli
e660: 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 te3_mutex] to be
e670: 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 an.** abstract
e680: 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 type for a mutex
e690: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 object. The SQ
e6a0: 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 Lite core never
e6b0: 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 looks.** at the
e6c0: 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 internal represe
e6d0: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 ntation of an [s
e6e0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 qlite3_mutex].
e6f0: 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 It only.** deals
e700: 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 with pointers t
e710: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d o the [sqlite3_m
e720: 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a utex] object..**
e730: 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 .** Mutexes are
e740: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 created using [s
e750: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c qlite3_mutex_all
e760: 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 oc()]..*/.typede
e770: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
e780: 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d _mutex sqlite3_m
e790: 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 utex;../*.** CAP
e7a0: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 I3REF: OS Interf
e7b0: 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a ace Object.**.**
e7c0: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 An instance of
e7d0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 the sqlite3_vfs
e7e0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 object defines t
e7f0: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 he interface bet
e800: 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 ween.** the SQLi
e810: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 te core and the
e820: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 underlying opera
e830: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 ting system. Th
e840: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 e "vfs".** in th
e850: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 e name of the ob
e860: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 ject stands for
e870: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 "virtual file sy
e880: 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 stem". See.** t
e890: 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f he [VFS | VFS do
e8a0: 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 cumentation] for
e8b0: 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 further informa
e8c0: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 tion..**.** The
e8d0: 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 value of the iVe
e8e0: 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 rsion field is i
e8f0: 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d nitially 1 but m
e900: 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a ay be larger in.
e910: 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f ** future versio
e920: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 ns of SQLite. A
e930: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 dditional fields
e940: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 may be appended
e950: 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 to this.** obje
e960: 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 ct when the iVer
e970: 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e sion value is in
e980: 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 creased. Note t
e990: 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72 hat the structur
e9a0: 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 e.** of the sqli
e9b0: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 te3_vfs object c
e9c0: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 hanges in the tr
e9d0: 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 ansaction betwee
e9e0: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 n.** SQLite vers
e9f0: 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e ion 3.5.9 and 3.
ea00: 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 6.0 and yet the
ea10: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 iVersion field w
ea20: 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 as not.** modifi
ea30: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a ed..**.** The sz
ea40: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 OsFile field is
ea50: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 the size of the
ea60: 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 subclassed [sqli
ea70: 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 te3_file].** str
ea80: 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74 ucture used by t
ea90: 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 his VFS. mxPath
eaa0: 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 name is the maxi
eab0: 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a mum length of.**
eac0: 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 a pathname in t
ead0: 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 his VFS..**.** R
eae0: 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 egistered sqlite
eaf0: 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 3_vfs objects ar
eb00: 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b e kept on a link
eb10: 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 ed list formed b
eb20: 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 y.** the pNext p
eb30: 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 ointer. The [sq
eb40: 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 lite3_vfs_regist
eb50: 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 er()].** and [sq
eb60: 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 lite3_vfs_unregi
eb70: 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 ster()] interfac
eb80: 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c es manage this l
eb90: 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 ist.** in a thre
eba0: 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 ad-safe way. Th
ebb0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 e [sqlite3_vfs_f
ebc0: 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 ind()] interface
ebd0: 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 .** searches the
ebe0: 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 list. Neither
ebf0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
ec00: 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 code nor the VFS
ec10: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
ec20: 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 on should use th
ec30: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e e pNext pointer.
ec40: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 .**.** The pNext
ec50: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e field is the on
ec60: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 ly field in the
ec70: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 sqlite3_vfs.** s
ec80: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51 tructure that SQ
ec90: 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d Lite will ever m
eca0: 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 odify. SQLite w
ecb0: 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a ill only access.
ecc0: 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 ** or modify thi
ecd0: 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f s field while ho
ece0: 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c lding a particul
ecf0: 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e ar static mutex.
ed00: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
ed10: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 ion should never
ed20: 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 modify anything
ed30: 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 within the sqli
ed40: 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 te3_vfs.** objec
ed50: 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 t once the objec
ed60: 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 t has been regis
ed70: 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 tered..**.** The
ed80: 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c zName field hol
ed90: 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 ds the name of t
eda0: 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 he VFS module.
edb0: 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a The name must.**
edc0: 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 be unique acros
edd0: 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 s all VFS module
ede0: 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 s..**.** [[sqlit
edf0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a e3_vfs.xOpen]].*
ee00: 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e * ^SQLite guaran
ee10: 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 tees that the zF
ee20: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 ilename paramete
ee30: 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 r to xOpen.** is
ee40: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 either a NULL p
ee50: 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 ointer or string
ee60: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f obtained.** fro
ee70: 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 m xFullPathname(
ee80: 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e ) with an option
ee90: 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e al suffix added.
eea0: 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 .** ^If a suffix
eeb0: 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 is added to the
eec0: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d zFilename param
eed0: 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a eter, it will.**
eee0: 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 consist of a si
eef0: 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 ngle "-" charact
ef00: 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e er followed by n
ef10: 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 o more than.** 1
ef20: 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 1 alphanumeric a
ef30: 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 nd/or "-" charac
ef40: 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 ters..** ^SQLite
ef50: 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 further guarant
ef60: 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 ees that.** the
ef70: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 string will be v
ef80: 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 alid and unchang
ef90: 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 ed until xClose(
efa0: 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 ) is.** called.
efb0: 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 Because of the p
efc0: 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 revious sentence
efd0: 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 ,.** the [sqlite
efe0: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 3_file] can safe
eff0: 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 ly store a point
f000: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c er to the.** fil
f010: 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 ename if it need
f020: 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 s to remember th
f030: 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 e filename for s
f040: 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 ome reason..** I
f050: 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 f the zFilename
f060: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 parameter to xOp
f070: 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 en is a NULL poi
f080: 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a nter then xOpen.
f090: 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 ** must invent i
f0a0: 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 ts own temporary
f0b0: 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 name for the fi
f0c0: 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 le. ^Whenever t
f0d0: 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 he .** xFilename
f0e0: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 parameter is NU
f0f0: 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 LL it will also
f100: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 be the case that
f110: 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 the.** flags pa
f120: 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 rameter will inc
f130: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 lude [SQLITE_OPE
f140: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d N_DELETEONCLOSE]
f150: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 ..**.** The flag
f160: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f s argument to xO
f170: 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 pen() includes a
f180: 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a ll bits set in.*
f190: 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 * the flags argu
f1a0: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 ment to [sqlite3
f1b0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 _open_v2()]. Or
f1c0: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 if [sqlite3_ope
f1d0: 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 n()].** or [sqli
f1e0: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 te3_open16()] is
f1f0: 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 used, then flag
f200: 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 s includes at le
f210: 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f ast.** [SQLITE_O
f220: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c PEN_READWRITE] |
f230: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 [SQLITE_OPEN_CR
f240: 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f EATE]. .** If xO
f250: 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 pen() opens a fi
f260: 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 le read-only the
f270: 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 n it sets *pOutF
f280: 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 lags to.** inclu
f290: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f de [SQLITE_OPEN_
f2a0: 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 READONLY]. Othe
f2b0: 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 r bits in *pOutF
f2c0: 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e lags may be set.
f2d0: 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 .**.** ^(SQLite
f2e0: 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e will also add on
f2f0: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 e of the followi
f300: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 ng flags to the
f310: 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c xOpen().** call,
f320: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 depending on th
f330: 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f e object being o
f340: 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c pened:.**.** <ul
f350: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 >.** <li> [SQLI
f360: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d TE_OPEN_MAIN_DB]
f370: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 .** <li> [SQLIT
f380: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 E_OPEN_MAIN_JOUR
f390: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 NAL].** <li> [S
f3a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f QLITE_OPEN_TEMP_
f3b0: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 DB].** <li> [SQ
f3c0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a LITE_OPEN_TEMP_J
f3d0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 OURNAL].** <li>
f3e0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 [SQLITE_OPEN_TR
f3f0: 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c ANSIENT_DB].** <
f400: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
f410: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a N_SUBJOURNAL].**
f420: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f <li> [SQLITE_O
f430: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e PEN_MASTER_JOURN
f440: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 AL].** <li> [SQ
f450: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a LITE_OPEN_WAL].*
f460: 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 * </ul>)^.**.**
f470: 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 The file I/O imp
f480: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 lementation can
f490: 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 use the object t
f4a0: 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 ype flags to.**
f4b0: 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 change the way i
f4c0: 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c t deals with fil
f4d0: 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 es. For example
f4e0: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e , an application
f4f0: 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f .** that does no
f500: 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 t care about cra
f510: 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 sh recovery or r
f520: 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 ollback might ma
f530: 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f ke.** the open o
f540: 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 f a journal file
f550: 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 a no-op. Write
f560: 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 s to this journa
f570: 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 l would.** also
f580: 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 be no-ops, and a
f590: 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 ny attempt to re
f5a0: 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 ad the journal w
f5b0: 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 ould return.** S
f5c0: 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 QLITE_IOERR. Or
f5d0: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 the implementat
f5e0: 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e ion might recogn
f5f0: 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62 ize that a datab
f600: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c ase.** file will
f610: 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 be doing page-a
f620: 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 ligned sector re
f630: 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 ads and writes i
f640: 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 n a random.** or
f650: 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 der and set up i
f660: 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d ts I/O subsystem
f670: 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a accordingly..**
f680: 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 .** SQLite might
f690: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 also add one of
f6a0: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 the following f
f6b0: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 lags to the xOpe
f6c0: 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 n method:.**.**
f6d0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 <ul>.** <li> [SQ
f6e0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 LITE_OPEN_DELETE
f6f0: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e ONCLOSE].** <li>
f700: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 [SQLITE_OPEN_EX
f710: 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c CLUSIVE].** </ul
f720: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c >.**.** The [SQL
f730: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f ITE_OPEN_DELETEO
f740: 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 NCLOSE] flag mea
f750: 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 ns the file shou
f760: 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 ld be.** deleted
f770: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 when it is clos
f780: 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 ed. ^The [SQLIT
f790: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 E_OPEN_DELETEONC
f7a0: 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 LOSE].** will be
f7b0: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 set for TEMP da
f7c0: 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 tabases and thei
f7d0: 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e r journals, tran
f7e0: 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 sient.** databas
f7f0: 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e es, and subjourn
f800: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 als..**.** ^The
f810: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 [SQLITE_OPEN_EXC
f820: 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 LUSIVE] flag is
f830: 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 always used in c
f840: 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 onjunction.** wi
f850: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f th the [SQLITE_O
f860: 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 PEN_CREATE] flag
f870: 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 , which are both
f880: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 directly.** ana
f890: 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f logous to the O_
f8a0: 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 EXCL and O_CREAT
f8b0: 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f flags of the PO
f8c0: 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 SIX open().** AP
f8d0: 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f I. The SQLITE_O
f8e0: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c PEN_EXCLUSIVE fl
f8f0: 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 ag, when paired
f900: 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c with the .** SQL
f910: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c ITE_OPEN_CREATE,
f920: 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 is used to indi
f930: 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 cate that file s
f940: 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 hould always.**
f950: 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 be created, and
f960: 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 that it is an er
f970: 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 ror if it alread
f980: 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 y exists..** It
f990: 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 is <i>not</i> us
f9a0: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 ed to indicate t
f9b0: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 he file should b
f9c0: 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 e opened .** for
f9d0: 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 exclusive acces
f9e0: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 s..**.** ^At lea
f9f0: 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 st szOsFile byte
fa00: 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 s of memory are
fa10: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c allocated by SQL
fa20: 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 ite.** to hold t
fa30: 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c he [sqlite3_fil
fa40: 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73 e] structure pas
fa50: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 sed as the third
fa60: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 .** argument to
fa70: 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 xOpen. The xOpe
fa80: 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f n method does no
fa90: 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c t have to.** all
faa0: 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74 ocate the struct
fab0: 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a ure; it should j
fac0: 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 ust fill it in.
fad0: 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 Note that.** th
fae0: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d e xOpen method m
faf0: 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 ust set the sqli
fb00: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 te3_file.pMethod
fb10: 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 s to either.** a
fb20: 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f valid [sqlite3_
fb30: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 io_methods] obje
fb40: 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 ct or to NULL.
fb50: 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a xOpen must do.**
fb60: 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 this even if th
fb70: 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 e open fails. S
fb80: 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68 QLite expects th
fb90: 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 at the sqlite3_f
fba0: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 ile.pMethods.**
fbb0: 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 element will be
fbc0: 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 valid after xOpe
fbd0: 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 n returns regard
fbe0: 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 less of the succ
fbf0: 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 ess.** or failur
fc00: 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 e of the xOpen c
fc10: 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c all..**.** [[sql
fc20: 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 ite3_vfs.xAccess
fc30: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 ]].** ^The flags
fc40: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 argument to xAc
fc50: 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 cess() may be [S
fc60: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 QLITE_ACCESS_EXI
fc70: 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 STS].** to test
fc80: 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 for the existenc
fc90: 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 e of a file, or
fca0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 [SQLITE_ACCESS_R
fcb0: 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 EADWRITE] to.**
fcc0: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 test whether a f
fcd0: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 ile is readable
fce0: 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 and writable, or
fcf0: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f [SQLITE_ACCESS_
fd00: 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 READ].** to test
fd10: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 whether a file
fd20: 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 is at least read
fd30: 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 able. The file
fd40: 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 can be a.** dir
fd50: 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 ectory..**.** ^S
fd60: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 QLite will alway
fd70: 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 s allocate at le
fd80: 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 ast mxPathname+1
fd90: 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a bytes for the.*
fda0: 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 * output buffer
fdb0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 xFullPathname.
fdc0: 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f The exact size o
fdd0: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 f the output buf
fde0: 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 fer.** is also p
fdf0: 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d assed as a param
fe00: 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 eter to both me
fe10: 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 thods. If the ou
fe20: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 tput buffer.** i
fe30: 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 s not large enou
fe40: 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 gh, [SQLITE_CANT
fe50: 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 OPEN] should be
fe60: 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 returned. Since
fe70: 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c this is.** handl
fe80: 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 ed as a fatal er
fe90: 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 ror by SQLite, v
fea0: 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f fs implementatio
feb0: 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 ns should endeav
fec0: 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 or.** to prevent
fed0: 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 this by setting
fee0: 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 mxPathname to a
fef0: 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 sufficiently la
ff00: 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a rge value..**.**
ff10: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 The xRandomness
ff20: 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 (), xSleep(), xC
ff30: 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e urrentTime(), an
ff40: 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e d xCurrentTimeIn
ff50: 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 t64().** interfa
ff60: 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 ces are not stri
ff70: 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 ctly a part of t
ff80: 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 he filesystem, b
ff90: 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 ut they are.** i
ffa0: 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 ncluded in the V
ffb0: 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 FS structure for
ffc0: 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a completeness..*
ffd0: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 * The xRandomnes
ffe0: 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 s() function att
fff0: 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 empts to return
10000 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 nBytes bytes.**
10010 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 of good-quality
10020 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 randomness into
10030 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 zOut. The retur
10040 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 n value is.** th
10050 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 e actual number
10060 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 of bytes of rand
10070 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e omness obtained.
10080 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 .** The xSleep()
10090 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 method causes t
100a0 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 he calling threa
100b0 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 d to sleep for a
100c0 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e t.** least the n
100d0 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 umber of microse
100e0 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 conds given. ^T
100f0 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 he xCurrentTime(
10100 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 ).** method retu
10110 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 rns a Julian Day
10120 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 Number for the
10130 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 current date and
10140 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c time as.** a fl
10150 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c oating point val
10160 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 ue..** ^The xCur
10170 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 rentTimeInt64()
10180 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 method returns,
10190 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 as an integer, t
101a0 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 he Julian.** Day
101b0 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 Number multipli
101c0 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28 ed by 86400000 (
101d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 the number of mi
101e0 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a lliseconds in .*
101f0 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 * a 24-hour day)
10200 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 . .** ^SQLite w
10210 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 ill use the xCur
10220 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 rentTimeInt64()
10230 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 method to get th
10240 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 e current.** dat
10250 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 e and time if th
10260 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 at method is ava
10270 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 ilable (if iVers
10280 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 ion is 2 or .**
10290 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 greater and the
102a0 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 function pointer
102b0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e is not NULL) an
102c0 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b d will fall back
102d0 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 .** to xCurrentT
102e0 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e ime() if xCurren
102f0 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 tTimeInt64() is
10300 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a unavailable..**.
10310 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 ** ^The xSetSyst
10320 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 emCall(), xGetSy
10330 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 stemCall(), and
10340 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 xNestSystemCall(
10350 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 ) interfaces.**
10360 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 are not used by
10370 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e the SQLite core.
10380 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c These optional
10390 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 interfaces are
103a0 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 provided.** by s
103b0 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 ome VFSes to fac
103c0 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 ilitate testing
103d0 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e of the VFS code.
103e0 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a By overriding .
103f0 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 ** system calls
10400 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 with functions u
10410 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c nder its control
10420 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d , a test program
10430 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 can.** simulate
10440 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f faults and erro
10450 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 r conditions tha
10460 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 t would otherwis
10470 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a e be difficult.*
10480 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 * or impossible
10490 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 to induce. The
104a0 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 set of system ca
104b0 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 lls that can be
104c0 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 overridden.** va
104d0 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 ries from one VF
104e0 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e S to another, an
104f0 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 d from one versi
10500 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 on of the same V
10510 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 FS to the.** nex
10520 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 t. Applications
10530 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20 that use these
10540 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 interfaces must
10550 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 be prepared for
10560 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 any.** or all of
10570 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 these interface
10580 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 s to be NULL or
10590 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69 for their behavi
105a0 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 or to change.**
105b0 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 from one release
105c0 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 to the next. A
105d0 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 pplications must
105e0 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 not attempt to
105f0 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 access.** any of
10600 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 these methods i
10610 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f f the iVersion o
10620 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 f the VFS is les
10630 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 s than 3..*/.typ
10640 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
10650 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f te3_vfs sqlite3_
10660 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 vfs;.typedef voi
10670 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 d (*sqlite3_sysc
10680 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a all_ptr)(void);.
10690 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 struct sqlite3_v
106a0 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 fs {. int iVers
106b0 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 ion;
106c0 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72 /* Structure ver
106d0 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 sion number (cur
106e0 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 rently 3) */. i
106f0 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 nt szOsFile;
10700 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 /* Size
10710 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 of subclassed sq
10720 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 lite3_file */.
10730 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 int mxPathname;
10740 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 /* Maxi
10750 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d mum file pathnam
10760 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 e length */. sq
10770 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 lite3_vfs *pNext
10780 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 ; /* Next r
10790 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f egistered VFS */
107a0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
107b0 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e Name; /* N
107c0 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 ame of this virt
107d0 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 ual file system
107e0 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 */. void *pAppD
107f0 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a ata; /*
10800 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c Pointer to appl
10810 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 ication-specific
10820 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 data */. int (
10830 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f *xOpen)(sqlite3_
10840 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 vfs*, const char
10850 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 *zName, sqlite3
10860 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 _file*,.
10870 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 int flags
10880 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 , int *pOutFlags
10890 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 );. int (*xDele
108a0 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a te)(sqlite3_vfs*
108b0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
108c0 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 ame, int syncDir
108d0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 );. int (*xAcce
108e0 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a ss)(sqlite3_vfs*
108f0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
10900 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 ame, int flags,
10910 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 int *pResOut);.
10920 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 int (*xFullPath
10930 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 name)(sqlite3_vf
10940 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a s*, const char *
10950 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c zName, int nOut,
10960 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 char *zOut);.
10970 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 void *(*xDlOpen)
10980 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 (sqlite3_vfs*, c
10990 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 onst char *zFile
109a0 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a name);. void (*
109b0 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 xDlError)(sqlite
109c0 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 3_vfs*, int nByt
109d0 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 e, char *zErrMsg
109e0 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 );. void (*(*xD
109f0 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 lSym)(sqlite3_vf
10a00 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 s*,void*, const
10a10 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 char *zSymbol))(
10a20 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a void);. void (*
10a30 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 xDlClose)(sqlite
10a40 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 3_vfs*, void*);.
10a50 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e int (*xRandomn
10a60 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ess)(sqlite3_vfs
10a70 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 *, int nByte, ch
10a80 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 ar *zOut);. int
10a90 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 (*xSleep)(sqlit
10aa0 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 e3_vfs*, int mic
10ab0 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e roseconds);. in
10ac0 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 t (*xCurrentTime
10ad0 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
10ae0 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 double*);. int
10af0 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 (*xGetLastError)
10b00 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 (sqlite3_vfs*, i
10b10 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f nt, char *);. /
10b20 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f *. ** The metho
10b30 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 ds above are in
10b40 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 version 1 of the
10b50 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 sqlite_vfs obje
10b60 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 ct. ** definiti
10b70 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 on. Those that
10b80 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 follow are added
10b90 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 in version 2 or
10ba0 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e later. */. in
10bb0 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 t (*xCurrentTime
10bc0 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 Int64)(sqlite3_v
10bd0 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 fs*, sqlite3_int
10be0 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 64*);. /*. **
10bf0 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 The methods abov
10c00 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e e are in version
10c10 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 s 1 and 2 of the
10c20 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 sqlite_vfs obje
10c30 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 ct.. ** Those b
10c40 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 elow are for ver
10c50 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 sion 3 and great
10c60 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 er.. */. int (
10c70 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 *xSetSystemCall)
10c80 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 (sqlite3_vfs*, c
10c90 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
10ca0 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c , sqlite3_syscal
10cb0 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 l_ptr);. sqlite
10cc0 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 3_syscall_ptr (*
10cd0 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 xGetSystemCall)(
10ce0 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f sqlite3_vfs*, co
10cf0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 nst char *zName)
10d00 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a ;. const char *
10d10 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c (*xNextSystemCal
10d20 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c l)(sqlite3_vfs*,
10d30 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
10d40 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 me);. /*. ** T
10d50 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 he methods above
10d60 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 are in versions
10d70 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 1 through 3 of
10d80 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f the sqlite_vfs o
10d90 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 bject.. ** New
10da0 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 fields may be ap
10db0 70 65 6e 64 65 64 20 69 6e 20 66 75 74 75 72 65 pended in future
10dc0 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 versions. The
10dd0 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 iVersion. ** va
10de0 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 lue will increme
10df0 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 nt whenever this
10e00 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a happens. . */.
10e10 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 };../*.** CAPI3R
10e20 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 EF: Flags for th
10e30 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 e xAccess VFS me
10e40 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 thod.**.** These
10e50 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e integer constan
10e60 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 ts can be used a
10e70 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 s the third para
10e80 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 meter to.** the
10e90 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f xAccess method o
10ea0 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 f an [sqlite3_vf
10eb0 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 s] object. They
10ec0 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 determine.** wh
10ed0 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 at kind of permi
10ee0 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 ssions the xAcce
10ef0 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f ss method is loo
10f00 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 king for..** Wit
10f10 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f h SQLITE_ACCESS_
10f20 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 EXISTS, the xAcc
10f30 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 ess method.** si
10f40 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 mply checks whet
10f50 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 her the file exi
10f60 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c sts..** With SQL
10f70 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 ITE_ACCESS_READW
10f80 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 RITE, the xAcces
10f90 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 s method.** chec
10fa0 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e ks whether the n
10fb0 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 amed directory i
10fc0 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 s both readable
10fd0 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 and writable.**
10fe0 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c (in other words,
10ff0 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 if files can be
11000 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c added, removed,
11010 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 and renamed wit
11020 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 hin.** the direc
11030 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 tory)..** The SQ
11040 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 LITE_ACCESS_READ
11050 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 WRITE constant i
11060 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 s currently used
11070 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 only by the.**
11080 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 [temp_store_dire
11090 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 ctory pragma], t
110a0 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 hough this could
110b0 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 change in a fut
110c0 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f ure.** release o
110d0 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 f SQLite..** Wit
110e0 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f h SQLITE_ACCESS_
110f0 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 READ, the xAcces
11100 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 s method.** chec
11110 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 ks whether the f
11120 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e ile is readable.
11130 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 The SQLITE_ACC
11140 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e ESS_READ constan
11150 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c t is.** currentl
11160 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 y unused, though
11170 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 it might be use
11180 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 d in a future re
11190 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 lease of.** SQLi
111a0 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 te..*/.#define S
111b0 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 QLITE_ACCESS_EXI
111c0 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 STS 0.#define
111d0 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 SQLITE_ACCESS_R
111e0 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 EADWRITE 1 /*
111f0 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 Used by PRAGMA t
11200 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 emp_store_direct
11210 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ory */.#define S
11220 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 QLITE_ACCESS_REA
11230 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e D 2 /* Un
11240 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 used */../*.** C
11250 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 API3REF: Flags f
11260 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 or the xShmLock
11270 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a VFS method.**.**
11280 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 These integer c
11290 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 onstants define
112a0 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b the various lock
112b0 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a ing operations.*
112c0 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 * allowed by the
112d0 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 xShmLock method
112e0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f of [sqlite3_io_
112f0 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a methods]. The.*
11300 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 * following are
11310 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 the only legal c
11320 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 ombinations of f
11330 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 lags to the.** x
11340 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a ShmLock method:.
11350 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
11360 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c i> SQLITE_SHM_L
11370 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d OCK | SQLITE_SHM
11380 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 _SHARED.** <li>
11390 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b SQLITE_SHM_LOCK
113a0 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 | SQLITE_SHM_EX
113b0 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 CLUSIVE.** <li>
113c0 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f SQLITE_SHM_UNLO
113d0 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f CK | SQLITE_SHM_
113e0 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 SHARED.** <li>
113f0 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 SQLITE_SHM_UNLOC
11400 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 K | SQLITE_SHM_E
11410 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c XCLUSIVE.** </ul
11420 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c >.**.** When unl
11430 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 ocking, the same
11440 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 SHARED or EXCLU
11450 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 SIVE flag must b
11460 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a e supplied as.**
11470 20 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74 68 was given on th
11480 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 e corresponding
11490 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 lock. .**.** Th
114a0 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f e xShmLock metho
114b0 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e d can transition
114c0 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 between unlocke
114d0 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a d and SHARED or.
114e0 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 ** between unloc
114f0 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 ked and EXCLUSIV
11500 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 E. It cannot tr
11510 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e ansition between
11520 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 SHARED.** and E
11530 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 XCLUSIVE..*/.#de
11540 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f fine SQLITE_SHM_
11550 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 UNLOCK 1.#
11560 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 define SQLITE_SH
11570 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 M_LOCK 2
11580 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
11590 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 SHM_SHARED
115a0 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 4.#define SQLIT
115b0 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 E_SHM_EXCLUSIVE
115c0 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 8../*.** CAPI
115d0 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 3REF: Maximum xS
115e0 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a hmLock index.**.
115f0 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 ** The xShmLock
11600 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 method on [sqlit
11610 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d e3_io_methods] m
11620 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a ay use values.**
11630 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 between 0 and t
11640 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 his upper bound
11650 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 as its "offset"
11660 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 argument..** The
11670 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c SQLite core wil
11680 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 l never attempt
11690 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 to acquire or re
116a0 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 lease a.** lock
116b0 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 outside of this
116c0 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 range.*/.#define
116d0 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 SQLITE_SHM_NLOC
116e0 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a K 8.../*.
116f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 ** CAPI3REF: Ini
11700 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 tialize The SQLi
11710 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a te Library.**.**
11720 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e ^The sqlite3_in
11730 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 itialize() routi
11740 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 ne initializes t
11750 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 he.** SQLite lib
11760 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 rary. ^The sqli
11770 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 te3_shutdown() r
11780 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f outine.** deallo
11790 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 cates any resour
117a0 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c ces that were al
117b0 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 located by sqlit
117c0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e e3_initialize().
117d0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
117e0 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 es are designed
117f0 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 to aid in proces
11800 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e s initialization
11810 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e and.** shutdown
11820 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 on embedded sys
11830 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 tems. Workstati
11840 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 on applications
11850 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 using.** SQLite
11860 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 normally do not
11870 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 need to invoke e
11880 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 ither of these r
11890 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 outines..**.** A
118a0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
118b0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 _initialize() is
118c0 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 an "effective"
118d0 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a call if it is.**
118e0 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 the first time
118f0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
11900 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 ze() is invoked
11910 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 during the lifet
11920 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 ime of.** the pr
11930 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 ocess, or if it
11940 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d is the first tim
11950 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 e sqlite3_initia
11960 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 lize() is invoke
11970 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 d.** following a
11980 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
11990 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 _shutdown(). ^(
119a0 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 Only an effectiv
119b0 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c e call.** of sql
119c0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
119d0 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 ) does any initi
119e0 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 alization. All
119f0 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 other calls.** a
11a00 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f re harmless no-o
11a10 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 ps.)^.**.** A ca
11a20 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 ll to sqlite3_sh
11a30 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 utdown() is an "
11a40 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 effective" call
11a50 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 if it is the fir
11a60 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 st.** call to sq
11a70 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
11a80 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 since the last
11a90 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
11aa0 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a ze(). ^(Only.**
11ab0 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 an effective ca
11ac0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 ll to sqlite3_sh
11ad0 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e utdown() does an
11ae0 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 y deinitializati
11af0 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 on..** All other
11b00 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 valid calls to
11b10 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
11b20 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 () are harmless
11b30 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 no-ops.)^.**.**
11b40 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 The sqlite3_init
11b50 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 ialize() interfa
11b60 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 ce is threadsafe
11b70 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 , but sqlite3_sh
11b80 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e utdown().** is n
11b90 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 ot. The sqlite3
11ba0 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 _shutdown() inte
11bb0 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 rface must only
11bc0 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 be called from a
11bd0 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 .** single threa
11be0 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 d. All open [da
11bf0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
11c00 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 ns] must be clos
11c10 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 ed and all.** ot
11c20 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 her SQLite resou
11c30 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 rces must be dea
11c40 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 llocated prior t
11c50 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 o invoking.** sq
11c60 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
11c70 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 ..**.** Among ot
11c80 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c her things, ^sql
11c90 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
11ca0 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a ) will invoke.**
11cb0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
11cc0 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 (). Similarly,
11cd0 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 ^sqlite3_shutdow
11ce0 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f n().** will invo
11cf0 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e ke sqlite3_os_en
11d00 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 d()..**.** ^The
11d10 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
11d20 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 ze() routine ret
11d30 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d urns [SQLITE_OK]
11d40 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 on success..**
11d50 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 ^If for some rea
11d60 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 son, sqlite3_ini
11d70 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 tialize() is una
11d80 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a ble to initializ
11d90 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 e.** the library
11da0 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20 (perhaps it is
11db0 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 unable to alloca
11dc0 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f te a needed reso
11dd0 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 urce such.** as
11de0 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 a mutex) it retu
11df0 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f rns an [error co
11e00 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b de] other than [
11e10 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a SQLITE_OK]..**.*
11e20 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 * ^The sqlite3_i
11e30 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 nitialize() rout
11e40 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e ine is called in
11e50 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 ternally by many
11e60 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 other.** SQLite
11e70 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 interfaces so t
11e80 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 hat an applicati
11e90 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 on usually does
11ea0 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 not need to.** i
11eb0 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e nvoke sqlite3_in
11ec0 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 itialize() direc
11ed0 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c tly. For exampl
11ee0 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e e, [sqlite3_open
11ef0 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c ()].** calls sql
11f00 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
11f10 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 ) so the SQLite
11f20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 library will be
11f30 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a automatically.**
11f40 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 initialized whe
11f50 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 n [sqlite3_open(
11f60 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 )] is called if
11f70 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e it has not be in
11f80 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 itialized.** alr
11f90 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c eady. ^However,
11fa0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f if SQLite is co
11fb0 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 mpiled with the
11fc0 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 [SQLITE_OMIT_AUT
11fd0 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c OINIT].** compil
11fe0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 e-time option, t
11ff0 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 hen the automati
12000 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 c calls to sqlit
12010 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a e3_initialize().
12020 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 ** are omitted a
12030 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 nd the applicati
12040 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c on must call sql
12050 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
12060 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 ) directly.** pr
12070 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 ior to using any
12080 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e other SQLite in
12090 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 terface. For ma
120a0 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 ximum portabilit
120b0 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f y,.** it is reco
120c0 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 mmended that app
120d0 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 lications always
120e0 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f invoke sqlite3_
120f0 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 initialize().**
12100 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 directly prior t
12110 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 o using any othe
12120 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 r SQLite interfa
12130 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 ce. Future rele
12140 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 ases.** of SQLit
12150 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 e may require th
12160 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f is. In other wo
12170 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f rds, the behavio
12180 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 r exhibited.** w
12190 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f hen SQLite is co
121a0 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c mpiled with [SQL
121b0 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 ITE_OMIT_AUTOINI
121c0 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 T] might become
121d0 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 the.** default b
121e0 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 ehavior in some
121f0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f future release o
12200 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 f SQLite..**.**
12210 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 The sqlite3_os_i
12220 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f nit() routine do
12230 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 es operating-sys
12240 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 tem specific.**
12250 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f initialization o
12260 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 f the SQLite lib
12270 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 rary. The sqlit
12280 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 e3_os_end().** r
12290 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 outine undoes th
122a0 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 e effect of sqli
122b0 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 te3_os_init().
122c0 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a Typical tasks.**
122d0 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 performed by th
122e0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 ese routines inc
122f0 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 lude allocation
12300 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a or deallocation.
12310 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 ** of static res
12320 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 ources, initiali
12330 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c zation of global
12340 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 variables,.** s
12350 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 etting up a defa
12360 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 ult [sqlite3_vfs
12370 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 ] module, or set
12380 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 ting up.** a def
12390 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 ault configurati
123a0 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 on using [sqlite
123b0 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 3_config()]..**.
123c0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 ** The applicati
123d0 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 on should never
123e0 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 invoke either sq
123f0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a lite3_os_init().
12400 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 ** or sqlite3_os
12410 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e _end() directly.
12420 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f The applicatio
12430 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e n should only in
12440 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f voke.** sqlite3_
12450 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 initialize() and
12460 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
12470 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 n(). The sqlite
12480 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 3_os_init().** i
12490 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c nterface is call
124a0 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ed automatically
124b0 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 by sqlite3_init
124c0 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 ialize() and.**
124d0 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 sqlite3_os_end()
124e0 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 is called by sq
124f0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
12500 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a . Appropriate.*
12510 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
12520 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 s for sqlite3_os
12530 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 _init() and sqli
12540 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 te3_os_end().**
12550 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 are built into S
12560 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 QLite when it is
12570 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e compiled for Un
12580 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 ix, Windows, or
12590 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 OS/2..** When [c
125a0 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 ustom builds | b
125b0 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 uilt for other p
125c0 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 latforms].** (us
125d0 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ing the [SQLITE_
125e0 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 OS_OTHER=1] comp
125f0 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 ile-time.** opti
12600 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 on) the applicat
12610 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 ion must supply
12620 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 a suitable imple
12630 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a mentation for.**
12640 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
12650 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f () and sqlite3_o
12660 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 s_end(). An app
12670 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 lication-supplie
12680 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 d.** implementat
12690 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f ion of sqlite3_o
126a0 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 s_init() or sqli
126b0 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 te3_os_end().**
126c0 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c must return [SQL
126d0 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 ITE_OK] on succe
126e0 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 ss and some othe
126f0 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 r [error code] u
12700 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a pon.** failure..
12710 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
12720 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
12730 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
12740 69 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 ize(void);.SQLIT
12750 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
12760 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
12770 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b _shutdown(void);
12780 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
12790 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
127a0 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 qlite3_os_init(v
127b0 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 oid);.SQLITE_API
127c0 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
127d0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 ALL sqlite3_os_e
127e0 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a nd(void);../*.**
127f0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 CAPI3REF: Confi
12800 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 guring The SQLit
12810 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 e Library.**.**
12820 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 The sqlite3_conf
12830 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 ig() interface i
12840 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 s used to make g
12850 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 lobal configurat
12860 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 ion.** changes t
12870 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 o SQLite in orde
12880 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 r to tune SQLite
12890 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 to the specific
128a0 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 needs of.** the
128b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 application. T
128c0 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 he default confi
128d0 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f guration is reco
128e0 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 mmended for most
128f0 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 .** applications
12900 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 and so this rou
12910 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 tine is usually
12920 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 not necessary.
12930 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 It is.** provide
12940 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 d to support rar
12950 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 e applications w
12960 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 ith unusual need
12970 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20 s..**.** <b>The
12980 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
12990 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f interface is no
129a0 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 54 68 t threadsafe. Th
129b0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a e application.**
129c0 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61 must ensure tha
129d0 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 t no other SQLit
129e0 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 e interfaces are
129f0 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 invoked by othe
12a00 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 r.** threads whi
12a10 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 le sqlite3_confi
12a20 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 3c g() is running.<
12a30 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 /b>.**.** The sq
12a40 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 lite3_config() i
12a50 6e 74 65 72 66 61 63 65 0a 2a 2a 20 6d 61 79 20 nterface.** may
12a60 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 only be invoked
12a70 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 prior to library
12a80 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 initialization
12a90 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 using.** [sqlite
12aa0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 3_initialize()]
12ab0 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 or after shutdow
12ac0 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 n by [sqlite3_sh
12ad0 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 utdown()]..** ^I
12ae0 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 f sqlite3_config
12af0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 () is called aft
12b00 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 er [sqlite3_init
12b10 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 ialize()] and be
12b20 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 fore.** [sqlite3
12b30 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 _shutdown()] the
12b40 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e n it will return
12b50 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a SQLITE_MISUSE..
12b60 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 ** Note, however
12b70 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f , that ^sqlite3_
12b80 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 config() can be
12b90 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f called as part o
12ba0 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 f the.** impleme
12bb0 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 ntation of an ap
12bc0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
12bd0 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e d [sqlite3_os_in
12be0 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 it()]..**.** The
12bf0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
12c00 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 to sqlite3_confi
12c10 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 g() is an intege
12c20 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 r.** [configurat
12c30 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 ion option] that
12c40 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 determines.** w
12c50 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 hat property of
12c60 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 SQLite is to be
12c70 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 configured. Sub
12c80 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 sequent argument
12c90 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 s.** vary depend
12ca0 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 ing on the [conf
12cb0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
12cc0 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 ].** in the firs
12cd0 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a t argument..**.*
12ce0 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 * ^When a config
12cf0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 uration option i
12d00 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 s set, sqlite3_c
12d10 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 onfig() returns
12d20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 [SQLITE_OK]..**
12d30 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 ^If the option i
12d40 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c s unknown or SQL
12d50 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f ite is unable to
12d60 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a set the option.
12d70 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 ** then this rou
12d80 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e tine returns a n
12d90 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 on-zero [error c
12da0 6f 64 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f ode]..*/.SQLITE_
12db0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 43 API int SQLITE_C
12dc0 44 45 43 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6e DECL sqlite3_con
12dd0 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a fig(int, ...);..
12de0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
12df0 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 Configure databa
12e00 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a se connections.*
12e10 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
12e20 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 3.**.** The sqli
12e30 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 te3_db_config()
12e40 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 interface is use
12e50 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 d to make config
12e60 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 uration.** chang
12e70 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 es to a [databas
12e80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 e connection].
12e90 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 The interface is
12ea0 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b similar to.** [
12eb0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
12ec0 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 ] except that th
12ed0 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 e changes apply
12ee0 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b to a single.** [
12ef0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
12f00 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 ion] (specified
12f10 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 in the first arg
12f20 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 ument)..**.** Th
12f30 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
12f40 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f t to sqlite3_db_
12f50 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 config(D,V,...)
12f60 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 is the.** [SQLI
12f70 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b TE_DBCONFIG_LOOK
12f80 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 ASIDE | configur
12f90 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e ation verb] - an
12fa0 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a integer code .*
12fb0 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 * that indicates
12fc0 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 what aspect of
12fd0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
12fe0 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 nnection] is bei
12ff0 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a ng configured..*
13000 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 * Subsequent arg
13010 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 uments vary depe
13020 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e nding on the con
13030 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e figuration verb.
13040 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f .**.** ^Calls to
13050 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 sqlite3_db_conf
13060 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 ig() return SQLI
13070 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c TE_OK if and onl
13080 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c y if.** the call
13090 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 is considered s
130a0 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51 uccessful..*/.SQ
130b0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
130c0 49 54 45 5f 43 44 45 43 4c 20 73 71 6c 69 74 65 ITE_CDECL sqlite
130d0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 3_db_config(sqli
130e0 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e te3*, int op, ..
130f0 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .);../*.** CAPI3
13100 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f REF: Memory Allo
13110 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a cation Routines.
13120 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 **.** An instanc
13130 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 e of this object
13140 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 defines the int
13150 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 erface between S
13160 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 QLite.** and low
13170 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c -level memory al
13180 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 location routine
13190 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 s..**.** This ob
131a0 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 ject is used in
131b0 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 only one place i
131c0 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 n the SQLite int
131d0 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 erface..** A poi
131e0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 nter to an insta
131f0 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 nce of this obje
13200 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 ct is the argume
13210 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 nt to.** [sqlite
13220 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 3_config()] when
13230 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 the configurati
13240 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 on option is.**
13250 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
13260 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 ALLOC] or [SQLIT
13270 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c E_CONFIG_GETMALL
13280 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 OC]. .** By cre
13290 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 ating an instanc
132a0 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 e of this object
132b0 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 .** and passing
132c0 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 it to [sqlite3_c
132d0 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 onfig]([SQLITE_C
132e0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a ONFIG_MALLOC]).*
132f0 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 * during configu
13300 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 ration, an appli
13310 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 cation can speci
13320 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 fy an alternativ
13330 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f e.** memory allo
13340 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d cation subsystem
13350 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 for SQLite to u
13360 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 se for all of it
13370 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d s.** dynamic mem
13380 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a ory needs..**.**
13390 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 Note that SQLit
133a0 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 e comes with sev
133b0 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d eral [built-in m
133c0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 emory allocators
133d0 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 ].** that are pe
133e0 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 rfectly adequate
133f0 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 for the overwhe
13400 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f lming majority o
13410 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a f applications.*
13420 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 * and that this
13430 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 object is only u
13440 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 seful to a tiny
13450 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c minority of appl
13460 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 ications.** with
13470 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d specialized mem
13480 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 ory allocation r
13490 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 equirements. Th
134a0 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 is object is.**
134b0 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 also used during
134c0 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 testing of SQLi
134d0 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 te in order to s
134e0 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e pecify an altern
134f0 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 ative.** memory
13500 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 allocator that s
13510 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 imulates memory
13520 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f out-of-memory co
13530 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f nditions in.** o
13540 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 rder to verify t
13550 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 hat SQLite recov
13560 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 ers gracefully f
13570 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 rom such.** cond
13580 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 itions..**.** Th
13590 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c e xMalloc, xReal
135a0 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d loc, and xFree m
135b0 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b ethods must work
135c0 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c like the.** mal
135d0 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 loc(), realloc()
135e0 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 and free() func
135f0 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 tions from the s
13600 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 tandard C librar
13610 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 y..** ^SQLite gu
13620 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 arantees that th
13630 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
13640 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 t to.** xRealloc
13650 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c is always a val
13660 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 ue returned by a
13670 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 prior call to x
13680 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 Roundup..**.** x
13690 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 Size should retu
136a0 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 rn the allocated
136b0 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 size of a memor
136c0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 y allocation.**
136d0 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 previously obtai
136e0 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 ned from xMalloc
136f0 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 or xRealloc. T
13700 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a he allocated siz
13710 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 e.** is always a
13720 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 t least as big a
13730 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 s the requested
13740 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 size but may be
13750 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 larger..**.** Th
13760 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f e xRoundup metho
13770 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 d returns what w
13780 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f ould be the allo
13790 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a cated size of.**
137a0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 a memory alloca
137b0 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 tion given a par
137c0 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 ticular requeste
137d0 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 d size. Most me
137e0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f mory.** allocato
137f0 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f rs round up memo
13800 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 ry allocations a
13810 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e t least to the n
13820 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 ext multiple.**
13830 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f of 8. Some allo
13840 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 cators round up
13850 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 to a larger mult
13860 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 iple or to a pow
13870 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 er of 2..** Ever
13880 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 y memory allocat
13890 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 ion request comi
138a0 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 ng in through [s
138b0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
138c0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f .** or [sqlite3_
138d0 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 realloc()] first
138e0 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e calls xRoundup.
138f0 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 If xRoundup re
13900 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 turns 0, .** tha
13910 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 t causes the cor
13920 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 responding memor
13930 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 y allocation to
13940 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 fail..**.** The
13950 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 xInit method ini
13960 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d tializes the mem
13970 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 ory allocator.
13980 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 For example,.**
13990 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 it might allocat
139a0 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 e any require mu
139b0 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c texes or initial
139c0 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 ize internal dat
139d0 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e a.** structures.
139e0 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 The xShutdown
139f0 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 method is invoke
13a00 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 d (indirectly) b
13a10 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 y.** [sqlite3_sh
13a20 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 utdown()] and sh
13a30 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 ould deallocate
13a40 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 any resources ac
13a50 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e quired.** by xIn
13a60 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 it. The pAppDat
13a70 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 a pointer is use
13a80 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 d as the only pa
13a90 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 rameter to.** xI
13aa0 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 nit and xShutdow
13ab0 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 n..**.** SQLite
13ac0 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 holds the [SQLIT
13ad0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d E_MUTEX_STATIC_M
13ae0 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 ASTER] mutex whe
13af0 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 n it invokes.**
13b00 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 the xInit method
13b10 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d , so the xInit m
13b20 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 ethod need not b
13b30 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 e threadsafe. T
13b40 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 he.** xShutdown
13b50 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 method is only c
13b60 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 alled from [sqli
13b70 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 te3_shutdown()]
13b80 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f so it does.** no
13b90 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 t need to be thr
13ba0 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 eadsafe either.
13bb0 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d For all other m
13bc0 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a ethods, SQLite.*
13bd0 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c * holds the [SQL
13be0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 ITE_MUTEX_STATIC
13bf0 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c _MEM] mutex as l
13c00 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 ong as the.** [S
13c10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d QLITE_CONFIG_MEM
13c20 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 STATUS] configur
13c30 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 ation option is
13c40 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 turned on (which
13c50 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 .** it is by def
13c60 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 ault) and so the
13c70 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 methods are aut
13c80 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 omatically seria
13c90 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 lized..** Howeve
13ca0 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f r, if [SQLITE_CO
13cb0 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 NFIG_MEMSTATUS]
13cc0 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 is disabled, the
13cd0 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d n the other.** m
13ce0 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 ethods must be t
13cf0 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 hreadsafe or els
13d00 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e e make their own
13d10 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f arrangements fo
13d20 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 r.** serializati
13d30 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 on..**.** SQLite
13d40 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f will never invo
13d50 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 ke xInit() more
13d60 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 than once withou
13d70 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 t an intervening
13d80 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 .** call to xShu
13d90 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 tdown()..*/.type
13da0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
13db0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 e3_mem_methods s
13dc0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
13dd0 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 ds;.struct sqlit
13de0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b e3_mem_methods {
13df0 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c . void *(*xMall
13e00 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 oc)(int);
13e10 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f /* Memory allo
13e20 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 cation function
13e30 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 */. void (*xFre
13e40 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 e)(void*);
13e50 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 /* Free a pr
13e60 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a ior allocation *
13e70 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 /. void *(*xRea
13e80 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 lloc)(void*,int)
13e90 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 ; /* Resize an
13ea0 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 allocation */.
13eb0 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 int (*xSize)(voi
13ec0 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f d*); /
13ed0 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a * Return the siz
13ee0 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 e of an allocati
13ef0 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 on */. int (*xR
13f00 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 oundup)(int);
13f10 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 /* Round
13f20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 up request size
13f30 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 to allocation si
13f40 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 ze */. int (*xI
13f50 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 nit)(void*);
13f60 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 /* Initia
13f70 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 lize the memory
13f80 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 allocator */. v
13f90 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 oid (*xShutdown)
13fa0 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a (void*); /*
13fb0 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 Deinitialize th
13fc0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
13fd0 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 or */. void *pA
13fe0 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 ppData;
13ff0 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 /* Argume
14000 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e nt to xInit() an
14010 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f d xShutdown() */
14020 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .};../*.** CAPI3
14030 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 REF: Configurati
14040 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 on Options.** KE
14050 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 YWORDS: {configu
14060 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a ration option}.*
14070 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 *.** These const
14080 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 ants are the ava
14090 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 ilable integer c
140a0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
140b0 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e ions that.** can
140c0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 be passed as th
140d0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
140e0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
140f0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 _config()] inter
14100 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 face..**.** New
14110 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
14120 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 tions may be add
14130 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c ed in future rel
14140 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e eases of SQLite.
14150 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e .** Existing con
14160 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
14170 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 ns might be disc
14180 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 ontinued. Appli
14190 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c cations.** shoul
141a0 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 d check the retu
141b0 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 rn code from [sq
141c0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
141d0 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 to make sure tha
141e0 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f t.** the call wo
141f0 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 rked. The [sqli
14200 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e te3_config()] in
14210 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 terface will ret
14220 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 urn a.** non-zer
14230 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 o [error code] i
14240 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 f a discontinued
14250 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 or unsupported
14260 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
14270 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b tion.** is invok
14280 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a ed..**.** <dl>.*
14290 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
142a0 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d G_SINGLETHREAD]]
142b0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
142c0 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c IG_SINGLETHREAD<
142d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 /dt>.** <dd>Ther
142e0 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e e are no argumen
142f0 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f ts to this optio
14300 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e n. ^This option
14310 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 sets the.** [th
14320 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f reading mode] to
14330 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 Single-thread.
14340 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c In other words,
14350 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 it disables.**
14360 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 all mutexing and
14370 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 puts SQLite int
14380 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 o a mode where i
14390 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 t can only be us
143a0 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c ed.** by a singl
143b0 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 e thread. ^If
143c0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
143d0 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b ed with.** the [
143e0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
143f0 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 E | SQLITE_THREA
14400 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 DSAFE=0] compile
14410 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 -time option the
14420 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 n.** it is not p
14430 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 ossible to chang
14440 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 e the [threading
14450 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 mode] from its
14460 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 default.** value
14470 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 of Single-threa
14480 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 d and so [sqlite
14490 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 3_config()] will
144a0 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c return .** [SQL
144b0 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 ITE_ERROR] if ca
144c0 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 lled with the SQ
144d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 LITE_CONFIG_SING
144e0 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 LETHREAD.** conf
144f0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
14500 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 .</dd>.**.** [[S
14510 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c QLITE_CONFIG_MUL
14520 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 TITHREAD]] <dt>S
14530 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c QLITE_CONFIG_MUL
14540 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a TITHREAD</dt>.**
14550 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e <dd>There are n
14560 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 o arguments to t
14570 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 his option. ^Th
14580 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 is option sets t
14590 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 he.** [threading
145a0 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d mode] to Multi-
145b0 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 thread. In othe
145c0 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 r words, it disa
145d0 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 bles.** mutexing
145e0 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f on [database co
145f0 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 nnection] and [p
14600 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
14610 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 t] objects..** T
14620 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 he application i
14630 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f s responsible fo
14640 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 r serializing ac
14650 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 cess to.** [data
14660 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
14670 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 ] and [prepared
14680 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 statements]. Bu
14690 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a t other mutexes.
146a0 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 ** are enabled s
146b0 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 o that SQLite wi
146c0 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 ll be safe to us
146d0 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 e in a multi-thr
146e0 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e eaded.** environ
146f0 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 ment as long as
14700 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 no two threads a
14710 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 ttempt to use th
14720 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 e same.** [datab
14730 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
14740 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 at the same time
14750 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 . ^If SQLite is
14760 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a compiled with.*
14770 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 * the [SQLITE_TH
14780 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 READSAFE | SQLIT
14790 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 E_THREADSAFE=0]
147a0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
147b0 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 ion then.** it i
147c0 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 s not possible t
147d0 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d o set the Multi-
147e0 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e thread [threadin
147f0 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b g mode] and.** [
14800 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
14810 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 ] will return [S
14820 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 QLITE_ERROR] if
14830 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a called with the.
14840 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ** SQLITE_CONFIG
14850 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e _MULTITHREAD con
14860 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
14870 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b n.</dd>.**.** [[
14880 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 SQLITE_CONFIG_SE
14890 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 RIALIZED]] <dt>S
148a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 QLITE_CONFIG_SER
148b0 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 IALIZED</dt>.**
148c0 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f <dd>There are no
148d0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 arguments to th
148e0 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 is option. ^Thi
148f0 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 s option sets th
14900 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 e.** [threading
14910 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 mode] to Seriali
14920 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f zed. In other wo
14930 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e rds, this option
14940 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 enables.** all
14950 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e mutexes includin
14960 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a g the recursive.
14970 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 ** mutexes on [d
14980 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
14990 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 on] and [prepare
149a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a d statement] obj
149b0 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 ects..** In this
149c0 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 mode (which is
149d0 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e the default when
149e0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
149f0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c led with.** [SQL
14a00 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 ITE_THREADSAFE=1
14a10 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 ]) the SQLite li
14a20 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c brary will itsel
14a30 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 f serialize acce
14a40 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 ss.** to [databa
14a50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 se connections]
14a60 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 and [prepared st
14a70 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 atements] so tha
14a80 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 t the.** applica
14a90 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 tion is free to
14aa0 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 use the same [da
14ab0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
14ac0 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d n] or the.** sam
14ad0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
14ae0 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 ement] in differ
14af0 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74 ent threads at t
14b00 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a he same time..**
14b10 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 ^If SQLite is c
14b20 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 ompiled with.**
14b30 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 the [SQLITE_THRE
14b40 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f ADSAFE | SQLITE_
14b50 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f THREADSAFE=0] co
14b60 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
14b70 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 n then.** it is
14b80 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 not possible to
14b90 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a set the Serializ
14ba0 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f ed [threading mo
14bb0 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 de] and.** [sqli
14bc0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 te3_config()] wi
14bd0 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 ll return [SQLIT
14be0 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c E_ERROR] if call
14bf0 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 ed with the.** S
14c00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 QLITE_CONFIG_SER
14c10 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 IALIZED configur
14c20 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 ation option.</d
14c30 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
14c40 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d E_CONFIG_MALLOC]
14c50 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
14c60 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a FIG_MALLOC</dt>.
14c70 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 ** <dd> ^(The SQ
14c80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c LITE_CONFIG_MALL
14c90 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 OC option takes
14ca0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e a single argumen
14cb0 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 t which is .** a
14cc0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
14cd0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b nstance of the [
14ce0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
14cf0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a ods] structure..
14d00 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 ** The argument
14d10 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 specifies.** alt
14d20 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 ernative low-lev
14d30 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 el memory alloca
14d40 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f tion routines to
14d50 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 be used in plac
14d60 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f e of.** the memo
14d70 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f ry allocation ro
14d80 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 utines built int
14d90 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c o SQLite.)^ ^SQL
14da0 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 ite makes.** its
14db0 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 own private cop
14dc0 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 y of the content
14dd0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
14de0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 _mem_methods] st
14df0 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 ructure.** befor
14e00 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 e the [sqlite3_c
14e10 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 onfig()] call re
14e20 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a turns.</dd>.**.*
14e30 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
14e40 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 G_GETMALLOC]] <d
14e50 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
14e60 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a GETMALLOC</dt>.*
14e70 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c * <dd> ^(The SQL
14e80 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 ITE_CONFIG_GETMA
14e90 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 LLOC option take
14ea0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d s a single argum
14eb0 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 ent which.** is
14ec0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
14ed0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 instance of the
14ee0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 [sqlite3_mem_met
14ef0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e hods] structure.
14f00 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 .** The [sqlite3
14f10 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a _mem_methods].**
14f20 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 structure is fi
14f30 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 lled with the cu
14f40 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 rrently defined
14f50 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
14f60 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a n routines.)^.**
14f70 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e This option can
14f80 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 be used to over
14f90 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 load the default
14fa0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
14fb0 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 on.** routines w
14fc0 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68 ith a wrapper th
14fd0 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d at simulations m
14fe0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
14ff0 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 failure or.** t
15000 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 racks memory usa
15010 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e ge, for example.
15020 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 </dd>.**.** [[S
15030 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d QLITE_CONFIG_MEM
15040 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c STATUS]] <dt>SQL
15050 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 ITE_CONFIG_MEMST
15060 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 ATUS</dt>.** <dd
15070 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f > ^The SQLITE_CO
15080 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f NFIG_MEMSTATUS o
15090 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 ption takes sing
150a0 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 le argument of t
150b0 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 ype int,.** inte
150c0 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f rpreted as a boo
150d0 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 lean, which enab
150e0 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 les or disables
150f0 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f the collection o
15100 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f f.** memory allo
15110 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 cation statistic
15120 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 s. ^(When memory
15130 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 allocation stat
15140 69 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 69 istics are.** di
15150 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c sabled, the foll
15160 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 owing SQLite int
15170 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e erfaces become n
15180 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a on-operational:.
15190 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c ** <ul>.** <
151a0 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d li> [sqlite3_mem
151b0 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 ory_used()].**
151c0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d <li> [sqlite3_m
151d0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 emory_highwater(
151e0 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 )].** <li> [sq
151f0 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f lite3_soft_heap_
15200 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 limit64()].**
15210 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 <li> [sqlite3_st
15220 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c atus64()].** <
15230 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 /ul>)^.** ^Memor
15240 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 y allocation sta
15250 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 tistics are enab
15260 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 led by default u
15270 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a nless SQLite is.
15280 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 ** compiled with
15290 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 [SQLITE_DEFAULT
152a0 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e _MEMSTATUS]=0 in
152b0 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f which case memo
152c0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e ry.** allocation
152d0 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 statistics are
152e0 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 disabled by defa
152f0 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a ult..** </dd>.**
15300 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
15310 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 FIG_SCRATCH]] <d
15320 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
15330 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 SCRATCH</dt>.**
15340 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 <dd> ^The SQLITE
15350 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 _CONFIG_SCRATCH
15360 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 option specifies
15370 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 a static memory
15380 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 buffer.** that
15390 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 SQLite can use f
153a0 6f 72 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 or scratch memor
153b0 79 2e 20 20 5e 28 54 68 65 72 65 20 61 72 65 20 y. ^(There are
153c0 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 0a three arguments.
153d0 2a 2a 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e ** to SQLITE_CON
153e0 46 49 47 5f 53 43 52 41 54 43 48 3a 20 20 41 20 FIG_SCRATCH: A
153f0 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 pointer an 8-byt
15400 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d e.** aligned mem
15410 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20 ory buffer from
15420 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63 which the scratc
15430 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 h allocations wi
15440 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 ll be.** drawn,
15450 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 the size of each
15460 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 scratch allocat
15470 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 ion (sz),.** and
15480 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d the maximum num
15490 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 ber of scratch a
154a0 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 29 llocations (N).)
154b0 5e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 ^.** The first a
154c0 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 rgument must be
154d0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
154e0 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 8-byte aligned b
154f0 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c uffer.** of at l
15500 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 east sz*N bytes
15510 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 of memory..** ^S
15520 51 4c 69 74 65 20 77 69 6c 6c 20 6e 6f 74 20 75 QLite will not u
15530 73 65 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 se more than one
15540 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73 scratch buffers
15550 20 70 65 72 20 74 68 72 65 61 64 2e 0a 2a 2a 20 per thread..**
15560 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 ^SQLite will nev
15570 65 72 20 72 65 71 75 65 73 74 20 61 20 73 63 72 er request a scr
15580 61 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74 atch buffer that
15590 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a is more than 6.
155a0 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 74 ** times the dat
155b0 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e abase page size.
155c0 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 6e .** ^If SQLite n
155d0 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 74 eeds needs addit
155e0 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 ional.** scratch
155f0 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 memory beyond w
15600 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 hat is provided
15610 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72 by this configur
15620 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 ation option, th
15630 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f en .** [sqlite3_
15640 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 malloc()] will b
15650 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e e used to obtain
15660 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 the memory need
15670 65 64 2e 3c 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20 ed.<p>.** ^When
15680 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
15690 70 72 6f 76 69 64 65 73 20 61 6e 79 20 61 6d 6f provides any amo
156a0 75 6e 74 20 6f 66 20 73 63 72 61 74 63 68 20 6d unt of scratch m
156b0 65 6d 6f 72 79 20 75 73 69 6e 67 0a 2a 2a 20 53 emory using.** S
156c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 QLITE_CONFIG_SCR
156d0 41 54 43 48 2c 20 53 51 4c 69 74 65 20 61 76 6f ATCH, SQLite avo
156e0 69 64 73 20 75 6e 6e 65 63 65 73 73 61 72 79 20 ids unnecessary
156f0 6c 61 72 67 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 large.** [sqlite
15700 33 5f 6d 61 6c 6c 6f 63 7c 68 65 61 70 20 61 6c 3_malloc|heap al
15710 6c 6f 63 61 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 locations]..** T
15720 68 69 73 20 63 61 6e 20 68 65 6c 70 20 5b 52 6f his can help [Ro
15730 62 73 6f 6e 20 70 72 6f 6f 66 7c 70 72 65 76 65 bson proof|preve
15740 6e 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 nt memory alloca
15750 74 69 6f 6e 20 66 61 69 6c 75 72 65 73 5d 20 64 tion failures] d
15760 75 65 20 74 6f 20 68 65 61 70 0a 2a 2a 20 66 72 ue to heap.** fr
15770 61 67 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 20 6c agmentation in l
15780 6f 77 2d 6d 65 6d 6f 72 79 20 65 6d 62 65 64 64 ow-memory embedd
15790 65 64 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c ed systems..** <
157a0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
157b0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 ITE_CONFIG_PAGEC
157c0 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 ACHE]] <dt>SQLIT
157d0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 E_CONFIG_PAGECAC
157e0 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 HE</dt>.** <dd>
157f0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 ^The SQLITE_CONF
15800 49 47 5f 50 41 47 45 43 41 43 48 45 20 6f 70 74 IG_PAGECACHE opt
15810 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 ion specifies a
15820 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74 memory pool.** t
15830 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 hat SQLite can u
15840 73 65 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 se for the datab
15850 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77 ase page cache w
15860 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 ith the default
15870 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d page.** cache im
15880 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a plementation. .
15890 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 ** This configur
158a0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 ation option is
158b0 61 20 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61 70 a no-op if an ap
158c0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
158d0 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 page.** cache i
158e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 mplementation is
158f0 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 loaded using th
15900 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 e [SQLITE_CONFIG
15910 5f 50 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54 _PCACHE2]..** ^T
15920 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 here are three a
15930 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 rguments to SQLI
15940 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 TE_CONFIG_PAGECA
15950 43 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 CHE: A pointer t
15960 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 o.** 8-byte alig
15970 6e 65 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65 6d ned memory (pMem
15980 29 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 ), the size of e
15990 61 63 68 20 70 61 67 65 20 63 61 63 68 65 20 6c ach page cache l
159a0 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 ine (sz),.** and
159b0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 the number of c
159c0 61 63 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e 0a ache lines (N)..
159d0 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 ** The sz argume
159e0 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 nt should be the
159f0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 size of the lar
15a00 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 gest database pa
15a10 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f ge.** (a power o
15a20 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 f two between 51
15a30 32 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75 2 and 65536) plu
15a40 73 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74 s some extra byt
15a50 65 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 es for each.** p
15a60 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 age header. ^Th
15a70 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 e number of extr
15a80 61 20 62 79 74 65 73 20 6e 65 65 64 65 64 20 62 a bytes needed b
15a90 79 20 74 68 65 20 70 61 67 65 20 68 65 61 64 65 y the page heade
15aa0 72 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 r.** can be dete
15ab0 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 5b 53 51 rmined using [SQ
15ac0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 LITE_CONFIG_PCAC
15ad0 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49 HE_HDRSZ]..** ^I
15ae0 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 t is harmless, a
15af0 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 part from the wa
15b00 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 sted memory,.**
15b10 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61 6d for the sz param
15b20 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67 65 eter to be large
15b30 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72 79 r than necessary
15b40 2e 20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 61 . The pMem.** a
15b50 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 rgument must be
15b60 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f either a NULL po
15b70 69 6e 74 65 72 20 6f 72 20 61 20 70 6f 69 6e 74 inter or a point
15b80 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a er to an 8-byte.
15b90 2a 2a 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b ** aligned block
15ba0 20 6f 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 of memory of at
15bb0 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 least sz*N byte
15bc0 73 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20 s, otherwise.**
15bd0 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 subsequent behav
15be0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 ior is undefined
15bf0 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d 20 ..** ^When pMem
15c00 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c is not NULL, SQL
15c10 69 74 65 20 77 69 6c 6c 20 73 74 72 69 76 65 20 ite will strive
15c20 74 6f 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 to use the memor
15c30 79 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74 6f y provided.** to
15c40 20 73 61 74 69 73 66 79 20 70 61 67 65 20 63 61 satisfy page ca
15c50 63 68 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c 69 che needs, falli
15c60 6e 67 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c 69 ng back to [sqli
15c70 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 66 te3_malloc()] if
15c80 0a 2a 2a 20 61 20 70 61 67 65 20 63 61 63 68 65 .** a page cache
15c90 20 6c 69 6e 65 20 69 73 20 6c 61 72 67 65 72 20 line is larger
15ca0 74 68 61 6e 20 73 7a 20 62 79 74 65 73 20 6f 72 than sz bytes or
15cb0 20 69 66 20 61 6c 6c 20 6f 66 20 74 68 65 20 70 if all of the p
15cc0 4d 65 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 Mem buffer.** is
15cd0 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e exhausted..** ^
15ce0 49 66 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c 20 If pMem is NULL
15cf0 61 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72 and N is non-zer
15d00 6f 2c 20 74 68 65 6e 20 65 61 63 68 20 64 61 74 o, then each dat
15d10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
15d20 0a 2a 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69 74 .** does an init
15d30 69 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 74 ial bulk allocat
15d40 69 6f 6e 20 66 6f 72 20 70 61 67 65 20 63 61 63 ion for page cac
15d50 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f he memory.** fro
15d60 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f m [sqlite3_mallo
15d70 63 28 29 5d 20 73 75 66 66 69 63 69 65 6e 74 20 c()] sufficient
15d80 66 6f 72 20 4e 20 63 61 63 68 65 20 6c 69 6e 65 for N cache line
15d90 73 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69 s if N is positi
15da0 76 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 32 ve or.** of -102
15db0 34 2a 4e 20 62 79 74 65 73 20 69 66 20 4e 20 69 4*N bytes if N i
15dc0 73 20 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e 49 s negative, . ^I
15dd0 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 f additional.**
15de0 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 page cache memor
15df0 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f y is needed beyo
15e00 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 nd what is provi
15e10 64 65 64 20 62 79 20 74 68 65 20 69 6e 69 74 69 ded by the initi
15e20 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e al.** allocation
15e30 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 67 6f , then SQLite go
15e40 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d es to [sqlite3_m
15e50 61 6c 6c 6f 63 28 29 5d 20 73 65 70 61 72 61 74 alloc()] separat
15e60 65 6c 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 ely for each.**
15e70 61 64 64 69 74 69 6f 6e 61 6c 20 63 61 63 68 65 additional cache
15e80 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a line. </dd>.**.
15e90 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
15ea0 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 IG_HEAP]] <dt>SQ
15eb0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 LITE_CONFIG_HEAP
15ec0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 </dt>.** <dd> ^T
15ed0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
15ee0 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 _HEAP option spe
15ef0 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 cifies a static
15f00 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a memory buffer .*
15f10 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 * that SQLite wi
15f20 6c 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f ll use for all o
15f30 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 f its dynamic me
15f40 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
15f50 6e 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 needs.** beyond
15f60 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66 those provided f
15f70 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f or by [SQLITE_CO
15f80 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e NFIG_SCRATCH] an
15f90 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e d.** [SQLITE_CON
15fa0 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a FIG_PAGECACHE]..
15fb0 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 ** ^The SQLITE_C
15fc0 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f ONFIG_HEAP optio
15fd0 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 n is only availa
15fe0 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 ble if SQLite is
15ff0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 compiled.** wit
16000 68 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 h either [SQLITE
16010 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d _ENABLE_MEMSYS3]
16020 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 or [SQLITE_ENAB
16030 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 LE_MEMSYS5] and
16040 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 returns.** [SQLI
16050 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 TE_ERROR] if inv
16060 6f 6b 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a oked otherwise..
16070 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 ** ^There are th
16080 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f ree arguments to
16090 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 SQLITE_CONFIG_H
160a0 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 EAP:.** An 8-byt
160b0 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 e aligned pointe
160c0 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c r to the memory,
160d0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f .** the number o
160e0 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d f bytes in the m
160f0 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e emory buffer, an
16100 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c d the minimum al
16110 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a location size..*
16120 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 * ^If the first
16130 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d pointer (the mem
16140 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 ory pointer) is
16150 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 NULL, then SQLit
16160 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 e reverts.** to
16170 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c using its defaul
16180 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 t memory allocat
16190 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d or (the system m
161a0 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e alloc() implemen
161b0 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f tation),.** undo
161c0 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e ing any prior in
161d0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c vocation of [SQL
161e0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f ITE_CONFIG_MALLO
161f0 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 C]. ^If the.**
16200 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 memory pointer i
16210 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 s not NULL then
16220 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 the alternative
16230 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 memory.** alloca
16240 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 tor is engaged t
16250 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 o handle all of
16260 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 SQLites memory a
16270 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e llocation needs.
16280 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f .** The first po
16290 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 inter (the memor
162a0 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 y pointer) must
162b0 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e be aligned to an
162c0 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 8-byte.** bound
162d0 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e ary or subsequen
162e0 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 t behavior of SQ
162f0 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 Lite will be und
16300 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d efined..** The m
16310 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f inimum allocatio
16320 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 n size is capped
16330 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f at 2**12. Reaso
16340 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 nable values.**
16350 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 for the minimum
16360 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 allocation size
16370 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 are 2**5 through
16380 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2**8.</dd>.**.*
16390 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
163a0 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 G_MUTEX]] <dt>SQ
163b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 LITE_CONFIG_MUTE
163c0 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e X</dt>.** <dd> ^
163d0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 (The SQLITE_CONF
163e0 49 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 IG_MUTEX option
163f0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 takes a single a
16400 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 rgument which is
16410 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f a.** pointer to
16420 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 an instance of
16430 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 the [sqlite3_mut
16440 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 ex_methods] stru
16450 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 cture..** The ar
16460 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 gument specifies
16470 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 alternative low
16480 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 -level mutex rou
16490 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 tines to be used
164a0 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65 .** in place the
164b0 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 mutex routines
164c0 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 built into SQLit
164d0 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 e.)^ ^SQLite ma
164e0 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a kes a copy of.**
164f0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 the content of
16500 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 the [sqlite3_mut
16510 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 ex_methods] stru
16520 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 cture before the
16530 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c call to.** [sql
16540 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 ite3_config()] r
16550 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 eturns. ^If SQLi
16560 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
16570 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 ith.** the [SQLI
16580 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 TE_THREADSAFE |
16590 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
165a0 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d E=0] compile-tim
165b0 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a e option then.**
165c0 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 the entire mute
165d0 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 xing subsystem i
165e0 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 s omitted from t
165f0 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e he build and hen
16600 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b ce calls to.** [
16610 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
16620 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 ] with the SQLIT
16630 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 E_CONFIG_MUTEX c
16640 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
16650 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 ion will.** retu
16660 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 rn [SQLITE_ERROR
16670 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b ].</dd>.**.** [[
16680 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
16690 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c TMUTEX]] <dt>SQL
166a0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 ITE_CONFIG_GETMU
166b0 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e TEX</dt>.** <dd>
166c0 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f ^(The SQLITE_CO
166d0 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 NFIG_GETMUTEX op
166e0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e tion takes a sin
166f0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 gle argument whi
16700 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 ch.** is a point
16710 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 er to an instanc
16720 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 e of the [sqlite
16730 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 3_mutex_methods]
16740 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 structure. The
16750 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 .** [sqlite3_mut
16760 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 ex_methods].** s
16770 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c tructure is fill
16780 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 ed with the curr
16790 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 ently defined mu
167a0 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a tex routines.)^.
167b0 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 ** This option c
167c0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 an be used to ov
167d0 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 erload the defau
167e0 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 lt mutex allocat
167f0 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 ion.** routines
16800 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75 with a wrapper u
16810 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 sed to track mut
16820 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 ex usage for per
16830 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 formance.** prof
16840 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 iling or testing
16850 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 , for example.
16860 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 ^If SQLite is c
16870 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 ompiled with.**
16880 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 the [SQLITE_THRE
16890 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f ADSAFE | SQLITE_
168a0 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f THREADSAFE=0] co
168b0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
168c0 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e n then.** the en
168d0 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 tire mutexing su
168e0 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 bsystem is omitt
168f0 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c ed from the buil
16900 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c d and hence call
16910 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 s to.** [sqlite3
16920 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 _config()] with
16930 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 the SQLITE_CONFI
16940 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 G_GETMUTEX confi
16950 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 guration option
16960 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b will.** return [
16970 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f SQLITE_ERROR].</
16980 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
16990 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 TE_CONFIG_LOOKAS
169a0 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 IDE]] <dt>SQLITE
169b0 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 _CONFIG_LOOKASID
169c0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e E</dt>.** <dd> ^
169d0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 (The SQLITE_CONF
169e0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 IG_LOOKASIDE opt
169f0 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 ion takes two ar
16a00 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 guments that det
16a10 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 ermine.** the de
16a20 66 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f fault size of lo
16a30 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f okaside memory o
16a40 6e 20 65 61 63 68 20 5b 64 61 74 61 62 61 73 65 n each [database
16a50 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a connection]..**
16a60 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
16a70 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 ent is the.** si
16a80 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 ze of each looka
16a90 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 side buffer slot
16aa0 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 and the second
16ab0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 is the number of
16ac0 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 .** slots alloca
16ad0 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 ted to each data
16ae0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e base connection.
16af0 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e )^ ^(SQLITE_CON
16b00 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a FIG_LOOKASIDE.**
16b10 20 73 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66 sets the <i>def
16b20 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 ault</i> lookasi
16b30 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 de size. The [SQ
16b40 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f LITE_DBCONFIG_LO
16b50 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 OKASIDE].** opti
16b60 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 on to [sqlite3_d
16b70 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 b_config()] can
16b80 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 be used to chang
16b90 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a e the lookaside.
16ba0 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ** configuration
16bb0 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 on individual c
16bc0 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f onnections.)^ </
16bd0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
16be0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 TE_CONFIG_PCACHE
16bf0 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 2]] <dt>SQLITE_C
16c00 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 ONFIG_PCACHE2</d
16c10 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 t>.** <dd> ^(The
16c20 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 SQLITE_CONFIG_P
16c30 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 CACHE2 option ta
16c40 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 kes a single arg
16c50 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a ument which is .
16c60 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ** a pointer to
16c70 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 an [sqlite3_pcac
16c80 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a he_methods2] obj
16c90 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 ect. This objec
16ca0 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 t specifies.** t
16cb0 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 he interface to
16cc0 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 a custom page ca
16cd0 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 che implementati
16ce0 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 on.)^.** ^SQLite
16cf0 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 makes a copy of
16d00 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 the [sqlite3_pc
16d10 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f ache_methods2] o
16d20 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a bject.</dd>.**.*
16d30 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
16d40 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c G_GETPCACHE2]] <
16d50 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
16d60 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e _GETPCACHE2</dt>
16d70 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 .** <dd> ^(The S
16d80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
16d90 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 PCACHE2 option t
16da0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 akes a single ar
16db0 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 gument which.**
16dc0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
16dd0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 an [sqlite3_pcac
16de0 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a he_methods2] obj
16df0 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 ect. SQLite cop
16e00 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 ies of.** the cu
16e10 72 72 65 6e 74 20 70 61 67 65 20 63 61 63 68 65 rrent page cache
16e20 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
16e30 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 into that object
16e40 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 .)^ </dd>.**.**
16e50 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
16e60 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 LOG]] <dt>SQLITE
16e70 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e _CONFIG_LOG</dt>
16e80 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c .** <dd> The SQL
16e90 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f ITE_CONFIG_LOG o
16ea0 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f ption is used to
16eb0 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53 configure the S
16ec0 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 QLite.** global
16ed0 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 [error log]..**
16ee0 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e (^The SQLITE_CON
16ef0 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 FIG_LOG option t
16f00 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e akes two argumen
16f10 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f ts: a pointer to
16f20 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 a.** function w
16f30 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 ith a call signa
16f40 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 ture of void(*)(
16f50 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 void*,int,const
16f60 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 char*), .** and
16f70 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 a pointer to voi
16f80 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 d. ^If the funct
16f90 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e ion pointer is n
16fa0 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a ot NULL, it is.*
16fb0 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 * invoked by [sq
16fc0 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 lite3_log()] to
16fd0 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 process each log
16fe0 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 ging event. ^If
16ff0 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e the.** function
17000 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c pointer is NULL
17010 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c , the [sqlite3_l
17020 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 og()] interface
17030 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e becomes a no-op.
17040 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f .** ^The void po
17050 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68 inter that is th
17060 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
17070 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 t to SQLITE_CONF
17080 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 IG_LOG is.** pas
17090 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 sed through as t
170a0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
170b0 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 er to the applic
170c0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f ation-defined lo
170d0 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e gger.** function
170e0 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 whenever that f
170f0 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b unction is invok
17100 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 ed. ^The second
17110 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a parameter to.**
17120 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 the logger func
17130 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f tion is a copy o
17140 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 f the first para
17150 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 meter to the cor
17160 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 responding.** [s
17170 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 qlite3_log()] ca
17180 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 ll and is intend
17190 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 ed to be a [resu
171a0 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a lt code] or an.*
171b0 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 * [extended resu
171c0 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 lt code]. ^The
171d0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
171e0 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f passed to the lo
171f0 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d gger is.** log m
17200 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 essage after for
17210 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c matting via [sql
17220 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d ite3_snprintf()]
17230 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 ..** The SQLite
17240 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 logging interfac
17250 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 e is not reentra
17260 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 nt; the logger f
17270 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c unction.** suppl
17280 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 ied by the appli
17290 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 cation must not
172a0 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 invoke any SQLit
172b0 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 e interface..**
172c0 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 In a multi-threa
172d0 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c ded application,
172e0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
172f0 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a -defined logger.
17300 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 ** function must
17310 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 be threadsafe.
17320 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
17330 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d LITE_CONFIG_URI]
17340 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
17350 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e FIG_URI.** <dd>^
17360 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 (The SQLITE_CONF
17370 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 IG_URI option ta
17380 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 kes a single arg
17390 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e ument of type in
173a0 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 t..** If non-zer
173b0 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 o, then URI hand
173c0 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 ling is globally
173d0 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 enabled. If the
173e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 parameter is ze
173f0 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 ro,.** then URI
17400 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 handling is glob
17410 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e ally disabled.)^
17420 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e ^If URI handlin
17430 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a g is globally.**
17440 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 enabled, all fi
17450 6c 65 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74 lenames passed t
17460 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 o [sqlite3_open(
17470 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 )], [sqlite3_ope
17480 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c n_v2()],.** [sql
17490 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f ite3_open16()] o
174a0 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 r.** specified a
174b0 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 s part of [ATTAC
174c0 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 H] commands are
174d0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 interpreted as U
174e0 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a RIs, regardless.
174f0 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 ** of whether or
17500 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 not the [SQLITE
17510 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 _OPEN_URI] flag
17520 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 is set when the
17530 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e database.** conn
17540 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 ection is opened
17550 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62 . ^If it is glob
17560 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 ally disabled, f
17570 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 ilenames are.**
17580 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 only interpreted
17590 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20 as URIs if the
175a0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 SQLITE_OPEN_URI
175b0 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e flag is set when
175c0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 the.** database
175d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f connection is o
175e0 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61 pened. ^(By defa
175f0 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e ult, URI handlin
17600 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a g is globally.**
17610 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 disabled. The d
17620 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 efault value may
17630 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 be changed by c
17640 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 ompiling with th
17650 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 e.** [SQLITE_USE
17660 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 _URI] symbol def
17670 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b ined.)^.**.** [[
17680 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f SQLITE_CONFIG_CO
17690 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 VERING_INDEX_SCA
176a0 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 N]] <dt>SQLITE_C
176b0 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 ONFIG_COVERING_I
176c0 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 NDEX_SCAN.** <dd
176d0 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e >^The SQLITE_CON
176e0 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 FIG_COVERING_IND
176f0 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 EX_SCAN option t
17700 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e akes a single in
17710 74 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e teger.** argumen
17720 74 20 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 t which is inter
17730 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c preted as a bool
17740 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 ean in order to
17750 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c enable or disabl
17760 65 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 e.** the use of
17770 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 covering indices
17780 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 for full table
17790 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 scans in the que
177a0 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a ry optimizer..**
177b0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 ^The default se
177c0 74 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 tting is determi
177d0 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 ned.** by the [S
177e0 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 QLITE_ALLOW_COVE
177f0 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d RING_INDEX_SCAN]
17800 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
17810 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 tion, or is "on"
17820 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 .** if that comp
17830 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile-time option
17840 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 is omitted..** T
17850 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 he ability to di
17860 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 sable the use of
17870 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 covering indice
17880 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 s for full table
17890 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 scans.** is bec
178a0 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 ause some incorr
178b0 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 ectly coded lega
178c0 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 cy applications
178d0 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f might malfunctio
178e0 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 n.** when the op
178f0 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e timization is en
17900 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e abled. Providin
17910 67 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f g the ability to
17920 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20 .** disable the
17930 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c optimization all
17940 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 ows the older, b
17950 75 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e uggy application
17960 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a code to work.**
17970 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20 without change
17980 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20 even with newer
17990 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
179a0 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 te..**.** [[SQLI
179b0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 TE_CONFIG_PCACHE
179c0 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ]] [[SQLITE_CONF
179d0 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a IG_GETPCACHE]].*
179e0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
179f0 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 FIG_PCACHE and S
17a00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
17a10 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 PCACHE.** <dd> T
17a20 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 hese options are
17a30 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 obsolete and sh
17a40 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 ould not be used
17a50 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a by new code..**
17a60 20 54 68 65 79 20 61 72 65 20 72 65 74 61 69 6e They are retain
17a70 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 ed for backwards
17a80 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 compatibility b
17a90 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 ut are now no-op
17aa0 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a s..** </dd>.**.*
17ab0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
17ac0 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 G_SQLLOG]].** <d
17ad0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
17ae0 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 SQLLOG.** <dd>Th
17af0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c is option is onl
17b00 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73 y available if s
17b10 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 qlite is compile
17b20 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 d with the.** [S
17b30 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c QLITE_ENABLE_SQL
17b40 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 LOG] pre-process
17b50 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 or macro defined
17b60 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 . The first argu
17b70 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 ment should.** b
17b80 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 e a pointer to a
17b90 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 function of typ
17ba0 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c e void(*)(void*,
17bb0 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 sqlite3*,const c
17bc0 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 har*, int)..** T
17bd0 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 he second should
17be0 20 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69 be of type (voi
17bf0 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 d*). The callbac
17c00 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 k is invoked by
17c10 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 the library.** i
17c20 6e 20 74 68 72 65 65 20 73 65 70 61 72 61 74 65 n three separate
17c30 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 circumstances,
17c40 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 identified by th
17c50 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 e value passed a
17c60 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 s the.** fourth
17c70 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68 parameter. If th
17c80 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
17c90 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 er is 0, then th
17ca0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
17cb0 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 ction.** passed
17cc0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 as the second ar
17cd0 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20 gument has just
17ce0 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 been opened. The
17cf0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a third argument.
17d00 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 ** points to a b
17d10 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 uffer containing
17d20 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
17d30 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 main database f
17d40 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 ile. If the.** f
17d50 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
17d60 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53 is 1, then the S
17d70 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 QL statement tha
17d80 74 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 t the third para
17d90 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 meter.** points
17da0 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e to has just been
17db0 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 executed. Or, i
17dc0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 f the fourth par
17dd0 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68 65 ameter is 2, the
17de0 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 n.** the connect
17df0 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64 ion being passed
17e00 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 as the second p
17e10 61 72 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e arameter is bein
17e20 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a g closed. The.**
17e30 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
17e40 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 is passed NULL
17e50 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20 41 In this case. A
17e60 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 n example of usi
17e70 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 ng this.** confi
17e80 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 guration option
17e90 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74 can be seen in t
17ea0 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e he "test_sqllog.
17eb0 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69 c" source file i
17ec0 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 n.** the canonic
17ed0 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 al SQLite source
17ee0 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a tree.</dd>.**.*
17ef0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
17f00 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a G_MMAP_SIZE]].**
17f10 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
17f20 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 IG_MMAP_SIZE.**
17f30 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dd>^SQLITE_CONF
17f40 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b IG_MMAP_SIZE tak
17f50 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e es two 64-bit in
17f60 74 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69 teger (sqlite3_i
17f70 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 nt64) values.**
17f80 74 68 61 74 20 61 72 65 20 74 68 65 20 64 65 66 that are the def
17f90 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c ault mmap size l
17fa0 69 6d 69 74 20 28 74 68 65 20 64 65 66 61 75 6c imit (the defaul
17fb0 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a t setting for.**
17fc0 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 [PRAGMA mmap_si
17fd0 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78 ze]) and the max
17fe0 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 imum allowed mma
17ff0 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a p size limit..**
18000 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 ^The default se
18010 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 tting can be ove
18020 72 72 69 64 64 65 6e 20 62 79 20 65 61 63 68 20 rridden by each
18030 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
18040 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 ion using.** eit
18050 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20 her the [PRAGMA
18060 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 mmap_size] comma
18070 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20 nd, or by using
18080 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 the.** [SQLITE_F
18090 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 CNTL_MMAP_SIZE]
180a0 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e file control. ^
180b0 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c (The maximum all
180c0 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a owed mmap size.*
180d0 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 * will be silent
180e0 6c 79 20 74 72 75 6e 63 61 74 65 64 20 69 66 20 ly truncated if
180f0 6e 65 63 65 73 73 61 72 79 20 73 6f 20 74 68 61 necessary so tha
18100 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 t it does not ex
18110 63 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 ceed the.** comp
18120 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d ile-time maximum
18130 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 mmap size set b
18140 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 y the.** [SQLITE
18150 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 _MAX_MMAP_SIZE]
18160 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
18170 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 ion.)^.** ^If ei
18180 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f ther argument to
18190 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 this option is
181a0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 negative, then t
181b0 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a hat argument is.
181c0 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 ** changed to it
181d0 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 s compile-time d
181e0 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b efault..**.** [[
181f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 SQLITE_CONFIG_WI
18200 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a N32_HEAPSIZE]].*
18210 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
18220 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 FIG_WIN32_HEAPSI
18230 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 ZE.** <dd>^The S
18240 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e QLITE_CONFIG_WIN
18250 33 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69 32_HEAPSIZE opti
18260 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c on is only avail
18270 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 able if SQLite i
18280 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f s.** compiled fo
18290 72 20 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74 r Windows with t
182a0 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 he [SQLITE_WIN32
182b0 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f _MALLOC] pre-pro
182c0 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 cessor macro.**
182d0 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 defined. ^SQLITE
182e0 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 _CONFIG_WIN32_HE
182f0 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33 APSIZE takes a 3
18300 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 2-bit unsigned i
18310 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 nteger value.**
18320 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74 that specifies t
18330 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 he maximum size
18340 6f 66 20 74 68 65 20 63 72 65 61 74 65 64 20 68 of the created h
18350 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c eap..**.** [[SQL
18360 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 ITE_CONFIG_PCACH
18370 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 E_HDRSZ]].** <dt
18380 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 >SQLITE_CONFIG_P
18390 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c CACHE_HDRSZ.** <
183a0 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 dd>^The SQLITE_C
183b0 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 ONFIG_PCACHE_HDR
183c0 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 SZ option takes
183d0 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 a single paramet
183e0 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 er which.** is a
183f0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
18400 6e 74 65 67 65 72 20 61 6e 64 20 77 72 69 74 65 nteger and write
18410 73 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 s into that inte
18420 67 65 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f ger the number o
18430 66 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 f extra.** bytes
18440 20 70 65 72 20 70 61 67 65 20 72 65 71 75 69 72 per page requir
18450 65 64 20 66 6f 72 20 65 61 63 68 20 70 61 67 65 ed for each page
18460 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 in [SQLITE_CONF
18470 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a IG_PAGECACHE]..*
18480 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 * The amount of
18490 65 78 74 72 61 20 73 70 61 63 65 20 72 65 71 75 extra space requ
184a0 69 72 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20 ired can change
184b0 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 depending on the
184c0 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 compiler,.** ta
184d0 72 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 rget platform, a
184e0 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f nd SQLite versio
184f0 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 n..**.** [[SQLIT
18500 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d E_CONFIG_PMASZ]]
18510 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 .** <dt>SQLITE_C
18520 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c ONFIG_PMASZ.** <
18530 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 dd>^The SQLITE_C
18540 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 ONFIG_PMASZ opti
18550 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
18560 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 e parameter whic
18570 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 h.** is an unsig
18580 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 ned integer and
18590 73 65 74 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 sets the "Minimu
185a0 6d 20 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 m PMA Size" for
185b0 74 68 65 20 6d 75 6c 74 69 74 68 72 65 61 64 65 the multithreade
185c0 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 d.** sorter to t
185d0 68 61 74 20 69 6e 74 65 67 65 72 2e 20 20 54 68 hat integer. Th
185e0 65 20 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 e default minimu
185f0 6d 20 50 4d 41 20 53 69 7a 65 20 69 73 20 73 65 m PMA Size is se
18600 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c t by the.** [SQL
18610 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a ITE_SORTER_PMASZ
18620 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
18630 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 ption. New thre
18640 61 64 73 20 61 72 65 20 6c 61 75 6e 63 68 65 64 ads are launched
18650 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 68 .** to help with
18660 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 sort operations
18670 20 77 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 when multithrea
18680 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 ded sorting.** i
18690 73 20 65 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 s enabled (using
186a0 20 74 68 65 20 5b 50 52 41 47 4d 41 20 74 68 72 the [PRAGMA thr
186b0 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 eads] command) a
186c0 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 nd the amount of
186d0 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 content.** to b
186e0 65 20 73 6f 72 74 65 64 20 65 78 63 65 65 64 73 e sorted exceeds
186f0 20 74 68 65 20 70 61 67 65 20 73 69 7a 65 20 74 the page size t
18700 69 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d imes the minimum
18710 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 of the.** [PRAG
18720 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 MA cache_size] s
18730 65 74 74 69 6e 67 20 61 6e 64 20 74 68 69 73 20 etting and this
18740 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 value..**.** [[S
18750 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d QLITE_CONFIG_STM
18760 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a 2a TJRNL_SPILL]].**
18770 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
18780 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c IG_STMTJRNL_SPIL
18790 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 L.** <dd>^The SQ
187a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 LITE_CONFIG_STMT
187b0 4a 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74 69 6f JRNL_SPILL optio
187c0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 n takes a single
187d0 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 parameter which
187e0 0a 2a 2a 20 62 65 63 6f 6d 65 73 20 74 68 65 20 .** becomes the
187f0 5b 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e [statement journ
18800 61 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64 69 73 al] spill-to-dis
18810 6b 20 74 68 72 65 73 68 6f 6c 64 2e 20 20 0a 2a k threshold. .*
18820 2a 20 5b 53 74 61 74 65 6d 65 6e 74 20 6a 6f 75 * [Statement jou
18830 72 6e 61 6c 73 5d 20 61 72 65 20 68 65 6c 64 20 rnals] are held
18840 69 6e 20 6d 65 6d 6f 72 79 20 75 6e 74 69 6c 20 in memory until
18850 74 68 65 69 72 20 73 69 7a 65 20 28 69 6e 20 62 their size (in b
18860 79 74 65 73 29 0a 2a 2a 20 65 78 63 65 65 64 73 ytes).** exceeds
18870 20 74 68 69 73 20 74 68 72 65 73 68 6f 6c 64 2c this threshold,
18880 20 61 74 20 77 68 69 63 68 20 70 6f 69 6e 74 20 at which point
18890 74 68 65 79 20 61 72 65 20 77 72 69 74 74 65 6e they are written
188a0 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72 20 to disk..** Or
188b0 69 66 20 74 68 65 20 74 68 72 65 73 68 6f 6c 64 if the threshold
188c0 20 69 73 20 2d 31 2c 20 73 74 61 74 65 6d 65 6e is -1, statemen
188d0 74 20 6a 6f 75 72 6e 61 6c 73 20 61 72 65 20 61 t journals are a
188e0 6c 77 61 79 73 20 68 65 6c 64 0a 2a 2a 20 65 78 lways held.** ex
188f0 63 6c 75 73 69 76 65 6c 79 20 69 6e 20 6d 65 6d clusively in mem
18900 6f 72 79 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d 61 ory..** Since ma
18910 6e 79 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 ny statement jou
18920 72 6e 61 6c 73 20 6e 65 76 65 72 20 62 65 63 6f rnals never beco
18930 6d 65 20 6c 61 72 67 65 2c 20 73 65 74 74 69 6e me large, settin
18940 67 20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a 20 74 g the spill.** t
18950 68 72 65 73 68 6f 6c 64 20 74 6f 20 61 20 76 61 hreshold to a va
18960 6c 75 65 20 73 75 63 68 20 61 73 20 36 34 4b 69 lue such as 64Ki
18970 42 20 63 61 6e 20 67 72 65 61 74 6c 79 20 72 65 B can greatly re
18980 64 75 63 65 20 74 68 65 20 61 6d 6f 75 6e 74 20 duce the amount
18990 6f 66 0a 2a 2a 20 49 2f 4f 20 72 65 71 75 69 72 of.** I/O requir
189a0 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 73 74 ed to support st
189b0 61 74 65 6d 65 6e 74 20 72 6f 6c 6c 62 61 63 6b atement rollback
189c0 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 ..** The default
189d0 20 76 61 6c 75 65 20 66 6f 72 20 74 68 69 73 20 value for this
189e0 73 65 74 74 69 6e 67 20 69 73 20 63 6f 6e 74 72 setting is contr
189f0 6f 6c 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 olled by the.**
18a00 5b 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52 4e 4c [SQLITE_STMTJRNL
18a10 5f 53 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65 2d _SPILL] compile-
18a20 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 time option..**
18a30 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 </dl>.*/.#define
18a40 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 SQLITE_CONFIG_S
18a50 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 INGLETHREAD 1
18a60 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e /* nil */.#defin
18a70 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
18a80 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 MULTITHREAD 2
18a90 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 /* nil */.#defi
18aa0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
18ab0 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 _SERIALIZED 3
18ac0 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 /* nil */.#def
18ad0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
18ae0 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 G_MALLOC
18af0 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 4 /* sqlite3_me
18b00 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 m_methods* */.#d
18b10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
18b20 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 FIG_GETMALLOC
18b30 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 5 /* sqlite3_
18b40 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a mem_methods* */.
18b50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
18b60 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 ONFIG_SCRATCH
18b70 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 6 /* void*,
18b80 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a int sz, int N *
18b90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
18ba0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 _CONFIG_PAGECACH
18bb0 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 E 7 /* void
18bc0 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e *, int sz, int N
18bd0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
18be0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 TE_CONFIG_HEAP
18bf0 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 8 /* vo
18c00 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 id*, int nByte,
18c10 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 int min */.#defi
18c20 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
18c30 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 _MEMSTATUS 9
18c40 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a /* boolean */.
18c50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
18c60 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 ONFIG_MUTEX
18c70 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 10 /* sqlite
18c80 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 3_mutex_methods*
18c90 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
18ca0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 TE_CONFIG_GETMUT
18cb0 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 EX 11 /* sq
18cc0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 lite3_mutex_meth
18cd0 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 ods* */./* previ
18ce0 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e ously SQLITE_CON
18cf0 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 FIG_CHUNKALLOC 1
18d00 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 2 which is now u
18d10 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 nused. */ .#defi
18d20 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
18d30 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 _LOOKASIDE 13
18d40 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a /* int int */.
18d50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
18d60 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 ONFIG_PCACHE
18d70 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 14 /* no-op
18d80 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
18d90 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 E_CONFIG_GETPCAC
18da0 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d HE 15 /* no-
18db0 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 op */.#define SQ
18dc0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 LITE_CONFIG_LOG
18dd0 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 16 /*
18de0 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a xFunc, void* */.
18df0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
18e00 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20 ONFIG_URI
18e10 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 17 /* int */
18e20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
18e30 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20 CONFIG_PCACHE2
18e40 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 18 /* sqlit
18e50 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 e3_pcache_method
18e60 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 s2* */.#define S
18e70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
18e80 50 43 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a PCACHE2 19 /*
18e90 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f sqlite3_pcache_
18ea0 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 methods2* */.#de
18eb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
18ec0 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 IG_COVERING_INDE
18ed0 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e X_SCAN 20 /* in
18ee0 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c t */.#define SQL
18ef0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f ITE_CONFIG_SQLLO
18f00 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78 G 21 /* x
18f10 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f Sqllog, void* */
18f20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
18f30 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 CONFIG_MMAP_SIZE
18f40 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74 22 /* sqlit
18f50 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65 e3_int64, sqlite
18f60 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69 3_int64 */.#defi
18f70 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
18f80 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 _WIN32_HEAPSIZE
18f90 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74 20 23 /* int
18fa0 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 nByte */.#define
18fb0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 SQLITE_CONFIG_P
18fc0 43 41 43 48 45 5f 48 44 52 53 5a 20 20 20 20 20 CACHE_HDRSZ
18fd0 20 20 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a 70 24 /* int *p
18fe0 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 sz */.#define SQ
18ff0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 LITE_CONFIG_PMAS
19000 5a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 Z
19010 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e 65 64 20 25 /* unsigned
19020 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a 23 64 65 int szPma */.#de
19030 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
19040 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c IG_STMTJRNL_SPIL
19050 4c 20 20 20 20 20 20 32 36 20 20 2f 2a 20 69 6e L 26 /* in
19060 74 20 6e 42 79 74 65 20 2a 2f 0a 0a 2f 2a 0a 2a t nByte */../*.*
19070 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 * CAPI3REF: Data
19080 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 base Connection
19090 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 Configuration Op
190a0 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 tions.**.** Thes
190b0 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 e constants are
190c0 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e the available in
190d0 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 teger configurat
190e0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 ion options that
190f0 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 .** can be passe
19100 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 d as the second
19110 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 argument to the
19120 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 [sqlite3_db_conf
19130 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e ig()] interface.
19140 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 .**.** New confi
19150 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 guration options
19160 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e may be added in
19170 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 future releases
19180 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 of SQLite..** E
19190 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 xisting configur
191a0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 ation options mi
191b0 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e ght be discontin
191c0 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f ued. Applicatio
191d0 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 ns.** should che
191e0 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f ck the return co
191f0 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 de from [sqlite3
19200 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f _db_config()] to
19210 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a make sure that.
19220 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b ** the call work
19230 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 ed. ^The [sqlit
19240 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 e3_db_config()]
19250 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 interface will r
19260 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a eturn a.** non-z
19270 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d ero [error code]
19280 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 if a discontinu
19290 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 ed or unsupporte
192a0 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 d configuration
192b0 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 option.** is inv
192c0 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e oked..**.** <dl>
192d0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 .** <dt>SQLITE_D
192e0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 BCONFIG_LOOKASID
192f0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e E</dt>.** <dd> ^
19300 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 This option take
19310 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e s three addition
19320 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 al arguments tha
19330 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 t determine the
19340 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d .** [lookaside m
19350 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d emory allocator]
19360 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 configuration f
19370 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 or the [database
19380 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a connection]..**
19390 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 ^The first argu
193a0 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 ment (the third
193b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 parameter to [sq
193c0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 lite3_db_config(
193d0 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 )] is a.** point
193e0 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 er to a memory b
193f0 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 uffer to use for
19400 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 lookaside memor
19410 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 y..** ^The first
19420 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 argument after
19430 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e the SQLITE_DBCON
19440 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 FIG_LOOKASIDE ve
19450 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c rb.** may be NUL
19460 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 L in which case
19470 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f SQLite will allo
19480 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b cate the.** look
19490 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73 aside buffer its
194a0 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 elf using [sqlit
194b0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 e3_malloc()]. ^T
194c0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
194d0 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a nt is the.** siz
194e0 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 e of each lookas
194f0 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e ide buffer slot.
19500 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 ^The third arg
19510 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d ument is the num
19520 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e ber of.** slots.
19530 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 The size of th
19540 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 e buffer in the
19550 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d first argument m
19560 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74 ust be greater t
19570 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 han.** or equal
19580 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f to the product o
19590 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 f the second and
195a0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 third arguments
195b0 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a . The buffer.**
195c0 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 must be aligned
195d0 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f to an 8-byte bo
195e0 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 undary. ^If the
195f0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
19600 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 to.** SQLITE_DB
19610 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 CONFIG_LOOKASIDE
19620 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 is not a multip
19630 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 le of 8, it is i
19640 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 nternally.** rou
19650 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 nded down to the
19660 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 next smaller mu
19670 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 ltiple of 8. ^(
19680 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 The lookaside me
19690 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 mory.** configur
196a0 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 ation for a data
196b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
196c0 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e can only be chan
196d0 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a ged when that.**
196e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e connection is n
196f0 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 ot currently usi
19700 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d ng lookaside mem
19710 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 ory, or in other
19720 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 words.** when t
19730 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75 he "current valu
19740 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a e" returned by.*
19750 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 * [sqlite3_db_st
19760 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f atus](D,[SQLITE_
19770 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 CONFIG_LOOKASIDE
19780 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a ],...) is zero..
19790 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 ** Any attempt t
197a0 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f o change the loo
197b0 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f kaside memory co
197c0 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e nfiguration when
197d0 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 lookaside.** me
197e0 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c mory is in use l
197f0 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67 eaves the config
19800 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 uration unchange
19810 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a d and returns .*
19820 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e * [SQLITE_BUSY].
19830 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 )^</dd>.**.** <d
19840 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 t>SQLITE_DBCONFI
19850 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 G_ENABLE_FKEY</d
19860 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 t>.** <dd> ^This
19870 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 option is used
19880 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 to enable or dis
19890 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65 able the enforce
198a0 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 ment of.** [fore
198b0 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 ign key constrai
198c0 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f nts]. There sho
198d0 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 uld be two addit
198e0 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e ional arguments.
198f0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 .** The first ar
19900 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 gument is an int
19910 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 eger which is 0
19920 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e to disable FK en
19930 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f forcement,.** po
19940 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 sitive to enable
19950 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 FK enforcement
19960 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c or negative to l
19970 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d eave FK enforcem
19980 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 ent.** unchanged
19990 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 . The second pa
199a0 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 rameter is a poi
199b0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 nter to an integ
199c0 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a er into which.**
199d0 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 is written 0 or
199e0 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 1 to indicate w
199f0 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 hether FK enforc
19a00 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 ement is off or
19a10 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 on.** following
19a20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 this call. The
19a30 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
19a40 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 may be a NULL p
19a50 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 ointer, in.** wh
19a60 69 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20 ich case the FK
19a70 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 enforcement sett
19a80 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 ing is not repor
19a90 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a ted back. </dd>.
19aa0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
19ab0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 _DBCONFIG_ENABLE
19ac0 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a _TRIGGER</dt>.**
19ad0 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 <dd> ^This opti
19ae0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e on is used to en
19af0 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 able or disable
19b00 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 [CREATE TRIGGER
19b10 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 | triggers]..**
19b20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 There should be
19b30 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 two additional a
19b40 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 rguments..** The
19b50 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
19b60 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 is an integer wh
19b70 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 ich is 0 to disa
19b80 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a ble triggers,.**
19b90 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 positive to ena
19ba0 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20 ble triggers or
19bb0 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 negative to leav
19bc0 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e e the setting un
19bd0 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 changed..** The
19be0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
19bf0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
19c00 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f an integer into
19c10 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 which.** is wri
19c20 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 tten 0 or 1 to i
19c30 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 ndicate whether
19c40 74 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73 triggers are dis
19c50 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 abled or enabled
19c60 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 .** following th
19c70 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 is call. The se
19c80 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d cond parameter m
19c90 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 ay be a NULL poi
19ca0 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 nter, in.** whic
19cb0 68 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67 h case the trigg
19cc0 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f er setting is no
19cd0 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e t reported back.
19ce0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 </dd>.**.** <dt
19cf0 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 >SQLITE_DBCONFIG
19d00 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b _ENABLE_FTS3_TOK
19d10 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c ENIZER</dt>.** <
19d20 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e dd> ^This option
19d30 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 is used to enab
19d40 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 le or disable th
19d50 65 20 74 77 6f 2d 61 72 67 75 6d 65 6e 74 0a 2a e two-argument.*
19d60 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 * version of the
19d70 20 5b 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 [fts3_tokenizer
19d80 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77 68 69 ()] function whi
19d90 63 68 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 ch is part of th
19da0 65 0a 2a 2a 20 5b 46 54 53 33 5d 20 66 75 6c 6c e.** [FTS3] full
19db0 2d 74 65 78 74 20 73 65 61 72 63 68 20 65 6e 67 -text search eng
19dc0 69 6e 65 20 65 78 74 65 6e 73 69 6f 6e 2e 0a 2a ine extension..*
19dd0 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 * There should b
19de0 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c e two additional
19df0 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 arguments..** T
19e00 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
19e10 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 t is an integer
19e20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 which is 0 to di
19e30 73 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e sable fts3_token
19e40 69 7a 65 72 28 29 20 6f 72 0a 2a 2a 20 70 6f 73 izer() or.** pos
19e50 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 itive to enable
19e60 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 fts3_tokenizer()
19e70 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 or negative to
19e80 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e leave the settin
19e90 67 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 0a g.** unchanged..
19ea0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 ** The second pa
19eb0 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 rameter is a poi
19ec0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 nter to an integ
19ed0 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a er into which.**
19ee0 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 is written 0 or
19ef0 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 1 to indicate w
19f00 68 65 74 68 65 72 20 66 74 73 33 5f 74 6f 6b 65 hether fts3_toke
19f10 6e 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 nizer is disable
19f20 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 d or enabled.**
19f30 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 following this c
19f40 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 all. The second
19f50 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 parameter may b
19f60 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 e a NULL pointer
19f70 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 , in.** which ca
19f80 73 65 20 74 68 65 20 6e 65 77 20 73 65 74 74 69 se the new setti
19f90 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 ng is not report
19fa0 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a ed back. </dd>.*
19fb0 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 *.** </dl>.*/.#d
19fc0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 efine SQLITE_DBC
19fd0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 ONFIG_LOOKASIDE
19fe0 20 20 20 20 20 20 20 20 20 20 20 20 31 30 30 31 1001
19ff0 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e /* void* int in
1a000 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c t */.#define SQL
1a010 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 ITE_DBCONFIG_ENA
1a020 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 20 20 20 BLE_FKEY
1a030 20 20 20 31 30 30 32 20 2f 2a 20 69 6e 74 20 69 1002 /* int i
1a040 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nt* */.#define S
1a050 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 QLITE_DBCONFIG_E
1a060 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20 20 20 NABLE_TRIGGER
1a070 20 20 20 20 20 31 30 30 33 20 2f 2a 20 69 6e 74 1003 /* int
1a080 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 int* */.#define
1a090 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 SQLITE_DBCONFIG
1a0a0 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b _ENABLE_FTS3_TOK
1a0b0 45 4e 49 5a 45 52 20 31 30 30 34 20 2f 2a 20 69 ENIZER 1004 /* i
1a0c0 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a nt int* */.../*.
1a0d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 ** CAPI3REF: Ena
1a0e0 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 ble Or Disable E
1a0f0 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 xtended Result C
1a100 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 odes.** METHOD:
1a110 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 sqlite3.**.** ^T
1a120 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e he sqlite3_exten
1a130 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 ded_result_codes
1a140 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c () routine enabl
1a150 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 es or disables t
1a160 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 he.** [extended
1a170 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 result codes] fe
1a180 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e ature of SQLite.
1a190 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 ^The extended r
1a1a0 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 esult.** codes a
1a1b0 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 re disabled by d
1a1c0 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f efault for histo
1a1d0 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c rical compatibil
1a1e0 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ity..*/.SQLITE_A
1a1f0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 PI int SQLITE_ST
1a200 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 78 DCALL sqlite3_ex
1a210 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f tended_result_co
1a220 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e des(sqlite3*, in
1a230 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a t onoff);../*.**
1a240 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 CAPI3REF: Last
1a250 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 20 Insert Rowid.**
1a260 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a METHOD: sqlite3.
1a270 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 **.** ^Each entr
1a280 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65 y in most SQLite
1a290 20 74 61 62 6c 65 73 20 28 65 78 63 65 70 74 20 tables (except
1a2a0 66 6f 72 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 for [WITHOUT ROW
1a2b0 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68 ID] tables).** h
1a2c0 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 as a unique 64-b
1a2d0 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 it signed.** int
1a2e0 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 eger key called
1a2f0 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f the [ROWID | "ro
1a300 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 wid"]. ^The rowi
1a310 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 d is always avai
1a320 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 lable.** as an u
1a330 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e ndeclared column
1a340 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 named ROWID, OI
1a350 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 D, or _ROWID_ as
1a360 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a long as those.*
1a370 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 * names are not
1a380 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 also used by exp
1a390 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 licitly declared
1a3a0 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a columns. ^If.**
1a3b0 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 the table has a
1a3c0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 column of type
1a3d0 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 [INTEGER PRIMARY
1a3e0 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 KEY] then that
1a3f0 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f column.** is ano
1a400 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 ther alias for t
1a410 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 he rowid..**.**
1a420 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 73 ^The sqlite3_las
1a430 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 t_insert_rowid(D
1a440 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
1a450 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 rns the [rowid]
1a460 6f 66 20 74 68 65 20 0a 2a 2a 20 6d 6f 73 74 20 of the .** most
1a470 72 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 recent successfu
1a480 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 l [INSERT] into
1a490 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 a rowid table or
1a4a0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d [virtual table]
1a4b0 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20 .** on database
1a4c0 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a connection D..**
1a4d0 20 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b ^Inserts into [
1a4e0 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 WITHOUT ROWID] t
1a4f0 61 62 6c 65 73 20 61 72 65 20 6e 6f 74 20 72 65 ables are not re
1a500 63 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e corded..** ^If n
1a510 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e o successful [IN
1a520 53 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 SERT]s into rowi
1a530 64 20 74 61 62 6c 65 73 0a 2a 2a 20 68 61 76 65 d tables.** have
1a540 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f ever occurred o
1a550 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 n the database c
1a560 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a onnection D, .**
1a570 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61 then sqlite3_la
1a580 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 st_insert_rowid(
1a590 44 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e D) returns zero.
1a5a0 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b .**.** ^(If an [
1a5b0 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 INSERT] occurs w
1a5c0 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 ithin a trigger
1a5d0 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72 or within a [vir
1a5e0 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d tual table].** m
1a5f0 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 ethod, then this
1a600 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 routine will re
1a610 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d turn the [rowid]
1a620 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 of the inserted
1a630 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 .** row as long
1a640 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20 6f as the trigger o
1a650 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 r virtual table
1a660 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e method is runnin
1a670 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 g..** But once t
1a680 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 he trigger or vi
1a690 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 rtual table meth
1a6a0 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c od ends, the val
1a6b0 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 ue returned .**
1a6c0 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 by this routine
1a6d0 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 20 reverts to what
1a6e0 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 68 it was before th
1a6f0 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 e trigger or vir
1a700 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 tual.** table me
1a710 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a thod began.)^.**
1a720 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d .** ^An [INSERT]
1a730 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 that fails due
1a740 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 to a constraint
1a750 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 violation is not
1a760 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c a.** successful
1a770 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f [INSERT] and do
1a780 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 es not change th
1a790 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
1a7a0 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 by this.** rout
1a7b0 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 ine. ^Thus INSE
1a7c0 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 RT OR FAIL, INSE
1a7d0 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e RT OR IGNORE, IN
1a7e0 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b SERT OR ROLLBACK
1a7f0 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 ,.** and INSERT
1a800 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f OR ABORT make no
1a810 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 changes to the
1a820 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 return value of
1a830 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 this.** routine
1a840 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 when their inser
1a850 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 tion fails. ^(W
1a860 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 hen INSERT OR RE
1a870 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 PLACE.** encount
1a880 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 ers a constraint
1a890 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 violation, it d
1a8a0 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 oes not fail. T
1a8b0 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e he.** INSERT con
1a8c0 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 tinues to comple
1a8d0 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 tion after delet
1a8e0 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 ing rows that ca
1a8f0 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 used.** the cons
1a900 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 traint problem s
1a910 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c o INSERT OR REPL
1a920 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 ACE will always
1a930 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 change.** the re
1a940 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 turn value of th
1a950 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a is interface.)^.
1a960 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 **.** ^For the p
1a970 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 urposes of this
1a980 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 routine, an [INS
1a990 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 ERT] is consider
1a9a0 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 ed to.** be succ
1a9b0 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 essful even if i
1a9c0 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c t is subsequentl
1a9d0 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a y rolled back..*
1a9e0 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 *.** This functi
1a9f0 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 on is accessible
1aa00 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e to SQL statemen
1aa10 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c ts via the.** [l
1aa20 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 ast_insert_rowid
1aa30 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d () SQL function]
1aa40 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 ..**.** If a sep
1aa50 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72 arate thread per
1aa60 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 forms a new [INS
1aa70 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 ERT] on the same
1aa80 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e .** database con
1aa90 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 nection while th
1aaa0 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f e [sqlite3_last_
1aab0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a insert_rowid()].
1aac0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 ** function is r
1aad0 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 unning and thus
1aae0 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 changes the last
1aaf0 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c insert [rowid],
1ab00 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c .** then the val
1ab10 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b ue returned by [
1ab20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 sqlite3_last_ins
1ab30 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a ert_rowid()] is.
1ab40 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 ** unpredictable
1ab50 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 and might not e
1ab60 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 qual either the
1ab70 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a old or the new.*
1ab80 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 * last insert [r
1ab90 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 owid]..*/.SQLITE
1aba0 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 _API sqlite3_int
1abb0 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 64 SQLITE_STDCAL
1abc0 4c 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 L sqlite3_last_i
1abd0 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 nsert_rowid(sqli
1abe0 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 te3*);../*.** CA
1abf0 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 PI3REF: Count Th
1ac00 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 e Number Of Rows
1ac10 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 Modified.** MET
1ac20 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a HOD: sqlite3.**.
1ac30 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f ** ^This functio
1ac40 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 n returns the nu
1ac50 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 mber of rows mod
1ac60 69 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20 ified, inserted
1ac70 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 or.** deleted by
1ac80 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
1ac90 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 ly completed INS
1aca0 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 ERT, UPDATE or D
1acb0 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 ELETE.** stateme
1acc0 6e 74 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 nt on the databa
1acd0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 se connection sp
1ace0 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f ecified by the o
1acf0 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a nly parameter..*
1ad00 2a 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 * ^Executing any
1ad10 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 other type of S
1ad20 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 QL statement doe
1ad30 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 s not modify the
1ad40 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e value.** return
1ad50 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 ed by this funct
1ad60 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 ion..**.** ^Only
1ad70 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69 changes made di
1ad80 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e rectly by the IN
1ad90 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 SERT, UPDATE or
1ada0 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 DELETE statement
1adb0 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 are.** consider
1adc0 65 64 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63 ed - auxiliary c
1add0 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 hanges caused by
1ade0 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 [CREATE TRIGGER
1adf0 20 7c 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a | triggers], .*
1ae00 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 * [foreign key a
1ae10 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c ctions] or [REPL
1ae20 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 ACE] constraint
1ae30 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e resolution are n
1ae40 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a ot counted..** .
1ae50 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20 ** Changes to a
1ae60 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e view that are in
1ae70 74 65 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a tercepted by .**
1ae80 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 [INSTEAD OF tri
1ae90 67 67 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f gger | INSTEAD O
1aea0 46 20 74 72 69 67 67 65 72 73 5d 20 61 72 65 20 F triggers] are
1aeb0 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 not counted. ^Th
1aec0 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 e value .** retu
1aed0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f rned by sqlite3_
1aee0 63 68 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 changes() immedi
1aef0 61 74 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49 ately after an I
1af00 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 NSERT, UPDATE or
1af10 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74 .** DELETE stat
1af20 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 ement run on a v
1af30 69 65 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65 iew is always ze
1af40 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 ro. Only changes
1af50 20 6d 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a made to real .*
1af60 2a 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75 * tables are cou
1af70 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e nted..**.** Thin
1af80 67 73 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 gs are more comp
1af90 6c 69 63 61 74 65 64 20 69 66 20 74 68 65 20 73 licated if the s
1afa0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 qlite3_changes()
1afb0 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 function is.**
1afc0 65 78 65 63 75 74 65 64 20 77 68 69 6c 65 20 61 executed while a
1afd0 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d trigger program
1afe0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 is running. Thi
1aff0 73 20 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20 s may happen if
1b000 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 the.** program u
1b010 73 65 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73 ses the [changes
1b020 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d () SQL function]
1b030 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 , or if some oth
1b040 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 er callback.** f
1b050 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 unction invokes
1b060 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 sqlite3_changes(
1b070 29 20 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65 ) directly. Esse
1b080 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 ntially:.** .**
1b090 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e <ul>.** <li> ^
1b0a0 28 42 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 (Before entering
1b0b0 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 a trigger progr
1b0c0 61 6d 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 am the value ret
1b0d0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 urned by.**
1b0e0 20 20 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 sqlite3_chang
1b0f0 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 es() function is
1b100 20 73 61 76 65 64 2e 20 41 66 74 65 72 20 74 68 saved. After th
1b110 65 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 e trigger progra
1b120 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73 m .** has
1b130 20 66 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f finished, the o
1b140 72 69 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 riginal value is
1b150 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 restored.)^.**
1b160 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 .** <li> ^(Wit
1b170 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 70 72 hin a trigger pr
1b180 6f 67 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52 ogram each INSER
1b190 54 2c 20 55 50 44 41 54 45 20 61 6e 64 20 44 45 T, UPDATE and DE
1b1a0 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 LETE .**
1b1b0 73 74 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74 statement sets t
1b1c0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
1b1d0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 d by sqlite3_cha
1b1e0 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 nges() .**
1b1f0 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f upon completio
1b200 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 n as normal. Of
1b210 63 6f 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c course, this val
1b220 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c ue will not incl
1b230 75 64 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 ude .** a
1b240 6e 79 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f ny changes perfo
1b250 72 6d 65 64 20 62 79 20 73 75 62 2d 74 72 69 67 rmed by sub-trig
1b260 67 65 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c gers, as the sql
1b270 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a ite3_changes() .
1b280 2a 2a 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 ** value
1b290 77 69 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e will be saved an
1b2a0 64 20 72 65 73 74 6f 72 65 64 20 61 66 74 65 72 d restored after
1b2b0 20 65 61 63 68 20 73 75 62 2d 74 72 69 67 67 65 each sub-trigge
1b2c0 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 r has run.)^.**
1b2d0 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 </ul>.** .** ^Th
1b2e0 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66 is means that if
1b2f0 20 74 68 65 20 63 68 61 6e 67 65 73 28 29 20 53 the changes() S
1b300 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 QL function (or
1b310 73 69 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64 similar) is used
1b320 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73 74 .** by the first
1b330 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 INSERT, UPDATE
1b340 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d or DELETE statem
1b350 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 ent within a tri
1b360 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 gger, it .** ret
1b370 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61 urns the value a
1b380 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 63 s set when the c
1b390 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 alling statement
1b3a0 20 62 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67 began executing
1b3b0 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75 ..** ^If it is u
1b3c0 73 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e sed by the secon
1b3d0 64 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 d or subsequent
1b3e0 73 75 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77 such statement w
1b3f0 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 ithin a trigger
1b400 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 .** program, the
1b410 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
1b420 72 65 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d reflects the num
1b430 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 ber of rows modi
1b440 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 fied by the .**
1b450 70 72 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c previous INSERT,
1b460 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 UPDATE or DELET
1b470 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 E statement with
1b480 69 6e 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 in the same trig
1b490 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ger..**.** See a
1b4a0 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 lso the [sqlite3
1b4b0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 _total_changes()
1b4c0 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 ] interface, the
1b4d0 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 .** [count_chang
1b4e0 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 es pragma], and
1b4f0 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 the [changes() S
1b500 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a QL function]..**
1b510 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 .** If a separat
1b520 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 e thread makes c
1b530 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 hanges on the sa
1b540 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e me database conn
1b550 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 ection.** while
1b560 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 [sqlite3_changes
1b570 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 ()] is running t
1b580 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 hen the value re
1b590 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 turned.** is unp
1b5a0 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e redictable and n
1b5b0 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a ot meaningful..*
1b5c0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
1b5d0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
1b5e0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 sqlite3_changes(
1b5f0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a sqlite3*);../*.*
1b600 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 * CAPI3REF: Tota
1b610 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 l Number Of Rows
1b620 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 Modified.** MET
1b630 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a HOD: sqlite3.**.
1b640 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f ** ^This functio
1b650 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f n returns the to
1b660 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f tal number of ro
1b670 77 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64 ws inserted, mod
1b680 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 ified or.** dele
1b690 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45 ted by all [INSE
1b6a0 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72 RT], [UPDATE] or
1b6b0 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d [DELETE] statem
1b6c0 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a ents completed.*
1b6d0 2a 20 73 69 6e 63 65 20 74 68 65 20 64 61 74 61 * since the data
1b6e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
1b6f0 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c was opened, incl
1b700 75 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65 63 uding those exec
1b710 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 uted as.** part
1b720 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 of trigger progr
1b730 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67 20 ams. ^Executing
1b740 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f any other type o
1b750 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a f SQL statement.
1b760 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66 65 ** does not affe
1b770 63 74 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 ct the value ret
1b780 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 urned by sqlite3
1b790 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 _total_changes()
1b7a0 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65 ..** .** ^Change
1b7b0 73 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f s made as part o
1b7c0 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 f [foreign key a
1b7d0 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c ctions] are incl
1b7e0 75 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63 uded in the.** c
1b7f0 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65 20 ount, but those
1b800 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20 made as part of
1b810 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 REPLACE constrai
1b820 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 nt resolution ar
1b830 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67 e.** not. ^Chang
1b840 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 es to a view tha
1b850 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65 t are intercepte
1b860 64 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46 20 d by INSTEAD OF
1b870 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72 65 triggers .** are
1b880 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a not counted..**
1b890 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 .** See also th
1b8a0 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 e [sqlite3_chang
1b8b0 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c es()] interface,
1b8c0 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 the.** [count_c
1b8d0 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 hanges pragma],
1b8e0 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 and the [total_c
1b8f0 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e hanges() SQL fun
1b900 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 ction]..**.** If
1b910 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 a separate thre
1b920 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 ad makes changes
1b930 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 on the same dat
1b940 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1b950 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 .** while [sqlit
1b960 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 e3_total_changes
1b970 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 ()] is running t
1b980 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a hen the value.**
1b990 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 returned is unp
1b9a0 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e redictable and n
1b9b0 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a ot meaningful..*
1b9c0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
1b9d0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
1b9e0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 sqlite3_total_ch
1b9f0 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b anges(sqlite3*);
1ba00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1ba10 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f : Interrupt A Lo
1ba20 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 ng-Running Query
1ba30 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
1ba40 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 te3.**.** ^This
1ba50 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 function causes
1ba60 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 any pending data
1ba70 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 base operation t
1ba80 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 o abort and.** r
1ba90 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 eturn at its ear
1baa0 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 liest opportunit
1bab0 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 y. This routine
1bac0 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 is typically.**
1bad0 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e called in respon
1bae0 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 se to a user act
1baf0 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 ion such as pres
1bb00 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a sing "Cancel".**
1bb10 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 or Ctrl-C where
1bb20 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 the user wants
1bb30 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 a long query ope
1bb40 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a ration to halt.*
1bb50 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a * immediately..*
1bb60 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 *.** ^It is safe
1bb70 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f to call this ro
1bb80 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 utine from a thr
1bb90 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 ead different fr
1bba0 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 om the.** thread
1bbb0 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 that is current
1bbc0 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 ly running the d
1bbd0 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f atabase operatio
1bbe0 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 n. But it.** is
1bbf0 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c not safe to cal
1bc00 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 l this routine w
1bc10 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 ith a [database
1bc20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 connection] that
1bc30 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 .** is closed or
1bc40 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 might close bef
1bc50 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 ore sqlite3_inte
1bc60 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e rrupt() returns.
1bc70 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 .**.** ^If an SQ
1bc80 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 L operation is v
1bc90 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 ery nearly finis
1bca0 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 hed at the time
1bcb0 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f when.** sqlite3_
1bcc0 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63 interrupt() is c
1bcd0 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d alled, then it m
1bce0 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e ight not have an
1bcf0 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 opportunity.**
1bd00 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 to be interrupte
1bd10 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 d and might cont
1bd20 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 inue to completi
1bd30 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 on..**.** ^An SQ
1bd40 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 L operation that
1bd50 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 is interrupted
1bd60 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c will return [SQL
1bd70 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a ITE_INTERRUPT]..
1bd80 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 ** ^If the inter
1bd90 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 rupted SQL opera
1bda0 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 tion is an INSER
1bdb0 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 T, UPDATE, or DE
1bdc0 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 LETE.** that is
1bdd0 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 inside an explic
1bde0 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 it transaction,
1bdf0 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 then the entire
1be00 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 transaction.** w
1be10 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 ill be rolled ba
1be20 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ck automatically
1be30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
1be40 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 ite3_interrupt(D
1be50 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 ) call is in eff
1be60 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 ect until all cu
1be70 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a rrently running.
1be80 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ** SQL statement
1be90 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 s on [database c
1bea0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d onnection] D com
1beb0 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 plete. ^Any new
1bec0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a SQL statements.
1bed0 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 ** that are star
1bee0 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 ted after the sq
1bef0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
1bf00 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 ) call and befor
1bf10 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e e the .** runnin
1bf20 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 g statements rea
1bf30 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e ches zero are in
1bf40 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20 terrupted as if
1bf50 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a they had been.**
1bf60 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 running prior t
1bf70 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e o the sqlite3_in
1bf80 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 terrupt() call.
1bf90 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d ^New SQL statem
1bfa0 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 ents.** that are
1bfb0 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 started after t
1bfc0 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 he running state
1bfd0 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 ment count reach
1bfe0 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e es zero are.** n
1bff0 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74 ot effected by t
1c000 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 he sqlite3_inter
1c010 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 rupt()..** ^A ca
1c020 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e ll to sqlite3_in
1c030 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20 terrupt(D) that
1c040 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 occurs when ther
1c050 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 e are no running
1c060 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e .** SQL statemen
1c070 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e ts is a no-op an
1c080 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 d has no effect
1c090 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 on SQL statement
1c0a0 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 s.** that are st
1c0b0 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 arted after the
1c0c0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
1c0d0 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 t() call returns
1c0e0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 ..**.** If the d
1c0f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1c100 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 on closes while
1c110 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 [sqlite3_interru
1c120 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e pt()].** is runn
1c130 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 ing then bad thi
1c140 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 ngs will likely
1c150 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 happen..*/.SQLIT
1c160 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 E_API void SQLIT
1c170 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
1c180 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 3_interrupt(sqli
1c190 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 te3*);../*.** CA
1c1a0 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e PI3REF: Determin
1c1b0 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 e If An SQL Stat
1c1c0 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 ement Is Complet
1c1d0 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f e.**.** These ro
1c1e0 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 utines are usefu
1c1f0 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 l during command
1c200 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 -line input to d
1c210 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a etermine if the.
1c220 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 ** currently ent
1c230 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 ered text seems
1c240 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 to form a comple
1c250 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 te SQL statement
1c260 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 or.** if additi
1c270 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 onal input is ne
1c280 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 eded before send
1c290 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 ing the text int
1c2a0 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 o.** SQLite for
1c2b0 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 parsing. ^These
1c2c0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
1c2d0 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 1 if the input
1c2e0 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 string.** appear
1c2f0 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 s to be a comple
1c300 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 te SQL statement
1c310 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 . ^A statement
1c320 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a is judged to be.
1c330 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 ** complete if i
1c340 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 t ends with a se
1c350 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e micolon token an
1c360 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 d is not a prefi
1c370 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 x of a.** well-f
1c380 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 ormed CREATE TRI
1c390 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 GGER statement.
1c3a0 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 ^Semicolons tha
1c3b0 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 t are embedded w
1c3c0 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 ithin.** string
1c3d0 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 literals or quot
1c3e0 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 ed identifier na
1c3f0 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 mes or comments
1c400 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 are not.** indep
1c410 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 endent tokens (t
1c420 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 hey are part of
1c430 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 the token in whi
1c440 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 ch they are.** e
1c450 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 mbedded) and thu
1c460 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 s do not count a
1c470 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 s a statement te
1c480 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 rminator. ^Whit
1c490 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f espace.** and co
1c4a0 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c mments that foll
1c4b0 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d ow the final sem
1c4c0 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 icolon are ignor
1c4d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 ed..**.** ^These
1c4e0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
1c4f0 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 0 if the statem
1c500 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 ent is incomplet
1c510 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d e. ^If a.** mem
1c520 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 ory allocation f
1c530 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 ails, then SQLIT
1c540 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 E_NOMEM is retur
1c550 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 ned..**.** ^Thes
1c560 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f e routines do no
1c570 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 t parse the SQL
1c580 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a statements thus.
1c590 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 ** will not dete
1c5a0 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 ct syntactically
1c5b0 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a incorrect SQL..
1c5c0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 **.** ^(If SQLit
1c5d0 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 e has not been i
1c5e0 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 nitialized using
1c5f0 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 [sqlite3_initia
1c600 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a lize()] prior .*
1c610 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 * to invoking sq
1c620 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 lite3_complete16
1c630 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f () then sqlite3_
1c640 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 initialize() is
1c650 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d invoked.** autom
1c660 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 atically by sqli
1c670 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 te3_complete16()
1c680 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 . If that initi
1c690 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c alization fails,
1c6a0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 .** then the ret
1c6b0 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 urn value from s
1c6c0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 qlite3_complete1
1c6d0 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 6() will be non-
1c6e0 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 zero.** regardle
1c6f0 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 ss of whether or
1c700 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 not the input S
1c710 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 QL is complete.)
1c720 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 ^.**.** The inpu
1c730 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f t to [sqlite3_co
1c740 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 mplete()] must b
1c750 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 e a zero-termina
1c760 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 ted.** UTF-8 str
1c770 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 ing..**.** The i
1c780 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 nput to [sqlite3
1c790 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d _complete16()] m
1c7a0 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 ust be a zero-te
1c7b0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d rminated.** UTF-
1c7c0 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 16 string in nat
1c7d0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a ive byte order..
1c7e0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
1c7f0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
1c800 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 sqlite3_complet
1c810 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 e(const char *sq
1c820 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 l);.SQLITE_API i
1c830 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c nt SQLITE_STDCAL
1c840 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 L sqlite3_comple
1c850 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 te16(const void
1c860 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 *sql);../*.** CA
1c870 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 PI3REF: Register
1c880 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 A Callback To H
1c890 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 andle SQLITE_BUS
1c8a0 59 20 45 72 72 6f 72 73 0a 2a 2a 20 4b 45 59 57 Y Errors.** KEYW
1c8b0 4f 52 44 53 3a 20 7b 62 75 73 79 2d 68 61 6e 64 ORDS: {busy-hand
1c8c0 6c 65 72 20 63 61 6c 6c 62 61 63 6b 7d 20 7b 62 ler callback} {b
1c8d0 75 73 79 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20 usy handler}.**
1c8e0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a METHOD: sqlite3.
1c8f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
1c900 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 e3_busy_handler(
1c910 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65 20 73 D,X,P) routine s
1c920 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 ets a callback f
1c930 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 unction X.** tha
1c940 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b t might be invok
1c950 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 ed with argument
1c960 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 P whenever.** a
1c970 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 n attempt is mad
1c980 65 20 74 6f 20 61 63 63 65 73 73 20 61 20 64 61 e to access a da
1c990 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 73 73 tabase table ass
1c9a0 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 ociated with.**
1c9b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
1c9c0 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f tion] D when ano
1c9d0 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f ther thread.** o
1c9e0 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 74 68 r process has th
1c9f0 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a e table locked..
1ca00 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 ** The sqlite3_b
1ca10 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e usy_handler() in
1ca20 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 terface is used
1ca30 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 to implement.**
1ca40 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 [sqlite3_busy_ti
1ca50 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50 52 meout()] and [PR
1ca60 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 AGMA busy_timeou
1ca70 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 t]..**.** ^If th
1ca80 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 e busy callback
1ca90 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 is NULL, then [S
1caa0 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 QLITE_BUSY].** i
1cab0 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 s returned immed
1cac0 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f iately upon enco
1cad0 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 untering the loc
1cae0 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 k. ^If the busy
1caf0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 callback.** is
1cb00 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 not NULL, then t
1cb10 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 he callback migh
1cb20 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 t be invoked wit
1cb30 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e h two arguments.
1cb40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 .**.** ^The firs
1cb50 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 t argument to th
1cb60 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 e busy handler i
1cb70 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 s a copy of the
1cb80 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 void* pointer wh
1cb90 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 ich.** is the th
1cba0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ird argument to
1cbb0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e sqlite3_busy_han
1cbc0 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 dler(). ^The se
1cbd0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f cond argument to
1cbe0 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e .** the busy han
1cbf0 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 dler callback is
1cc00 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 the number of t
1cc10 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 imes that the bu
1cc20 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a sy handler has.*
1cc30 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 70 * been invoked p
1cc40 72 65 76 69 6f 75 73 6c 79 20 66 6f 72 20 74 68 reviously for th
1cc50 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 e same locking e
1cc60 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a vent. ^If the.*
1cc70 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 * busy callback
1cc80 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 returns 0, then
1cc90 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 no additional at
1cca0 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 tempts are made
1ccb0 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 to.** access the
1ccc0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 database and [S
1ccd0 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 20 72 QLITE_BUSY] is r
1cce0 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 eturned.** to th
1ccf0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a e application..*
1cd00 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 * ^If the callba
1cd10 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a ck returns non-z
1cd20 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 ero, then anothe
1cd30 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 r attempt.** is
1cd40 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 74 made to access t
1cd50 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 he database and
1cd60 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 the cycle repeat
1cd70 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 s..**.** The pre
1cd80 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 sence of a busy
1cd90 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 handler does not
1cda0 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 guarantee that
1cdb0 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b it will be invok
1cdc0 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 ed.** when there
1cdd0 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 is lock content
1cde0 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 ion. ^If SQLite
1cdf0 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 determines that
1ce00 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 invoking the bus
1ce10 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 y.** handler cou
1ce20 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 ld result in a d
1ce30 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c eadlock, it will
1ce40 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 go ahead and re
1ce50 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 turn [SQLITE_BUS
1ce60 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 Y].** to the app
1ce70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74 65 61 64 lication instead
1ce80 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 of invoking the
1ce90 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 .** busy handle
1cea0 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 r..** Consider a
1ceb0 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 scenario where
1cec0 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 one process is h
1ced0 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f olding a read lo
1cee0 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 ck that.** it is
1cef0 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f trying to promo
1cf00 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 te to a reserved
1cf10 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 lock and.** a s
1cf20 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 econd process is
1cf30 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 holding a reser
1cf40 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 ved lock that it
1cf50 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f is trying.** to
1cf60 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 promote to an e
1cf70 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 xclusive lock.
1cf80 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 The first proces
1cf90 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 s cannot proceed
1cfa0 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 .** because it i
1cfb0 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 s blocked by the
1cfc0 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 second and the
1cfd0 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 second process c
1cfe0 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 annot.** proceed
1cff0 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 because it is b
1d000 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 locked by the fi
1d010 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 rst. If both pr
1d020 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b ocesses.** invok
1d030 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c e the busy handl
1d040 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c ers, neither wil
1d050 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 l make any progr
1d060 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c ess. Therefore,
1d070 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 .** SQLite retur
1d080 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d ns [SQLITE_BUSY]
1d090 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 for the first p
1d0a0 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 rocess, hoping t
1d0b0 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c hat this.** will
1d0c0 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 induce the firs
1d0d0 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c t process to rel
1d0e0 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f ease its read lo
1d0f0 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 ck and allow.**
1d100 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 the second proce
1d110 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a ss to proceed..*
1d120 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c *.** ^The defaul
1d130 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 t busy callback
1d140 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e is NULL..**.** ^
1d150 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 (There can only
1d160 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 be a single busy
1d170 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 handler defined
1d180 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 for each.** [da
1d190 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1d1a0 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e n]. Setting a n
1d1b0 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 ew busy handler
1d1c0 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 clears any.** pr
1d1d0 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e eviously set han
1d1e0 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 dler.)^ ^Note t
1d1f0 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c hat calling [sql
1d200 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 ite3_busy_timeou
1d210 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 t()].** or evalu
1d220 61 74 69 6e 67 20 5b 50 52 41 47 4d 41 20 62 75 ating [PRAGMA bu
1d230 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 sy_timeout=N] wi
1d240 6c 6c 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a ll change the.**
1d250 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 61 6e busy handler an
1d260 64 20 74 68 75 73 20 63 6c 65 61 72 20 61 6e 79 d thus clear any
1d270 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 previously set
1d280 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a busy handler..**
1d290 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c .** The busy cal
1d2a0 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 lback should not
1d2b0 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e take any action
1d2c0 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 s which modify t
1d2d0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 he.** database c
1d2e0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 onnection that i
1d2f0 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 nvoked the busy
1d300 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68 handler. In oth
1d310 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 er words,.** the
1d320 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 busy handler is
1d330 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 20 not reentrant.
1d340 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e Any such action
1d350 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 s.** result in u
1d360 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f ndefined behavio
1d370 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 r..** .** A busy
1d380 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f handler must no
1d390 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 t close the data
1d3a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a base connection.
1d3b0 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 ** or [prepared
1d3c0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 statement] that
1d3d0 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 invoked the busy
1d3e0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c handler..*/.SQL
1d3f0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 ITE_API int SQLI
1d400 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
1d410 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 e3_busy_handler(
1d420 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 sqlite3*, int(*)
1d430 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 (void*,int), voi
1d440 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 d*);../*.** CAPI
1d450 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 3REF: Set A Busy
1d460 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54 48 Timeout.** METH
1d470 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a OD: sqlite3.**.*
1d480 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 * ^This routine
1d490 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f sets a [sqlite3_
1d4a0 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 busy_handler | b
1d4b0 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 usy handler] tha
1d4c0 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 t sleeps.** for
1d4d0 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 a specified amou
1d4e0 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 nt of time when
1d4f0 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 a table is locke
1d500 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 d. ^The handler
1d510 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d .** will sleep m
1d520 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e ultiple times un
1d530 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 til at least "ms
1d540 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f " milliseconds o
1d550 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 f sleeping.** ha
1d560 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 ve accumulated.
1d570 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 ^After at least
1d580 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e "ms" millisecon
1d590 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a ds of sleeping,.
1d5a0 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 ** the handler r
1d5b0 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 eturns 0 which c
1d5c0 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 auses [sqlite3_s
1d5d0 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e tep()] to return
1d5e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 .** [SQLITE_BUSY
1d5f0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e ]..**.** ^Callin
1d600 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 g this routine w
1d610 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 ith an argument
1d620 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 less than or equ
1d630 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 al to zero.** tu
1d640 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 rns off all busy
1d650 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a handlers..**.**
1d660 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c ^(There can onl
1d670 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 y be a single bu
1d680 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 sy handler for a
1d690 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b particular.** [
1d6a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1d6b0 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69 76 65 ion] at any give
1d6c0 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e n moment. If an
1d6d0 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c other busy handl
1d6e0 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 er.** was define
1d6f0 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 d (using [sqlit
1d700 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 e3_busy_handler(
1d710 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c )]) prior to cal
1d720 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 ling.** this rou
1d730 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 tine, that other
1d740 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 busy handler is
1d750 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a cleared.)^.**.*
1d760 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52 * See also: [PR
1d770 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 AGMA busy_timeou
1d780 74 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 t].*/.SQLITE_API
1d790 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
1d7a0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 75 73 79 ALL sqlite3_busy
1d7b0 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 _timeout(sqlite3
1d7c0 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a *, int ms);../*.
1d7d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e ** CAPI3REF: Con
1d7e0 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 venience Routine
1d7f0 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 s For Running Qu
1d800 65 72 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a eries.** METHOD:
1d810 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 sqlite3.**.** T
1d820 68 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 his is a legacy
1d830 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69 interface that i
1d840 73 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 s preserved for
1d850 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 backwards compat
1d860 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 ibility..** Use
1d870 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 of this interfac
1d880 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 e is not recomme
1d890 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 nded..**.** Defi
1d8a0 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 nition: A <b>res
1d8b0 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 ult table</b> is
1d8c0 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 memory data str
1d8d0 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62 ucture created b
1d8e0 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 y the.** [sqlite
1d8f0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 3_get_table()] i
1d900 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 nterface. A res
1d910 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 ult table record
1d920 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 s the.** complet
1d930 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 e query results
1d940 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 from one or more
1d950 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 queries..**.**
1d960 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 The table concep
1d970 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d tually has a num
1d980 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 ber of rows and
1d990 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a columns. But.**
1d9a0 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 these numbers a
1d9b0 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 re not part of t
1d9c0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 he result table
1d9d0 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a itself. These.*
1d9e0 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 * numbers are ob
1d9f0 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c tained separatel
1da00 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 y. Let N be the
1da10 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a number of rows.
1da20 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 ** and M be the
1da30 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e number of column
1da40 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c s..**.** A resul
1da50 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 t table is an ar
1da60 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 ray of pointers
1da70 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 to zero-terminat
1da80 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 ed UTF-8 strings
1da90 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 ..** There are (
1daa0 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 N+1)*M elements
1dab0 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 in the array. T
1dac0 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 he first M point
1dad0 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 ers point.** to
1dae0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
1daf0 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f strings that co
1db00 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 ntain the names
1db10 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a of the columns..
1db20 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 ** The remaining
1db30 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 entries all poi
1db40 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 nt to query resu
1db50 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 lts. NULL value
1db60 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e s result.** in N
1db70 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 ULL pointers. A
1db80 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 ll other values
1db90 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 are in their UTF
1dba0 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 -8 zero-terminat
1dbb0 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 ed.** string rep
1dbc0 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 resentation as r
1dbd0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 eturned by [sqli
1dbe0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
1dbf0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 )]..**.** A resu
1dc00 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 lt table might c
1dc10 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 onsist of one or
1dc20 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c more memory all
1dc30 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 ocations..** It
1dc40 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 is not safe to p
1dc50 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 ass a result tab
1dc60 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b le directly to [
1dc70 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e sqlite3_free()].
1dc80 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 .** A result tab
1dc90 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 le should be dea
1dca0 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b llocated using [
1dcb0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 sqlite3_free_tab
1dcc0 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 le()]..**.** ^(A
1dcd0 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 s an example of
1dce0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 the result table
1dcf0 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 format, suppose
1dd00 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a a query result.
1dd10 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 ** is as follows
1dd20 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 :.**.** <blockqu
1dd30 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 ote><pre>.**
1dd40 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 Name
1dd50 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 | Age.**
1dd60 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
1dd70 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 -------.**
1dd80 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 Alice |
1dd90 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 43.** Bob
1dda0 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a | 28.**
1ddb0 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 Cindy
1ddc0 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 | 21.** </pr
1ddd0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a e></blockquote>.
1dde0 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 **.** There are
1ddf0 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 two column (M==2
1de00 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 ) and three rows
1de10 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 (N==3). Thus t
1de20 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 he.** result tab
1de30 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 le has 8 entries
1de40 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 . Suppose the r
1de50 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 esult table is s
1de60 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 tored.** in an a
1de70 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 rray names azRes
1de80 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 ult. Then azRes
1de90 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 ult holds this c
1dea0 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 ontent:.**.** <b
1deb0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
1dec0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
1ded0 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d lt[0] = "Nam
1dee0 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a e";.** az
1def0 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 Result[1] =
1df00 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 "Age";.**
1df10 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d azResult[2]
1df20 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 = "Alice";.**
1df30 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 azResult&#
1df40 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 91;3] = "43";.**
1df50 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 azResult
1df60 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b [4] = "Bob";
1df70 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 .** azRes
1df80 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 ult[5] = "28
1df90 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
1dfa0 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 esult[6] = "
1dfb0 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 Cindy";.**
1dfc0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 azResult[7
1dfd0 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 ] = "21";.** </p
1dfe0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e re></blockquote>
1dff0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 )^.**.** ^The sq
1e000 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 lite3_get_table(
1e010 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 ) function evalu
1e020 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 ates one or more
1e030 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 .** semicolon-se
1e040 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 parated SQL stat
1e050 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 ements in the ze
1e060 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 ro-terminated UT
1e070 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 F-8.** string of
1e080 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 its 2nd paramet
1e090 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 er and returns a
1e0a0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f result table to
1e0b0 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 the.** pointer
1e0c0 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 given in its 3rd
1e0d0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a parameter..**.*
1e0e0 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c * After the appl
1e0f0 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 ication has fini
1e100 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65 shed with the re
1e110 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 sult from sqlite
1e120 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 3_get_table(),.*
1e130 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 * it must pass t
1e140 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 he result table
1e150 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 pointer to sqlit
1e160 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 e3_free_table()
1e170 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 in order to.** r
1e180 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 elease the memor
1e190 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f y that was mallo
1e1a0 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 ced. Because of
1e1b0 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 the way the.**
1e1c0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
1e1d0 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 )] happens withi
1e1e0 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 n sqlite3_get_ta
1e1f0 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 ble(), the calli
1e200 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d ng.** function m
1e210 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 ust not try to c
1e220 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 all [sqlite3_fre
1e230 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 e()] directly.
1e240 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 Only.** [sqlite3
1e250 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 _free_table()] i
1e260 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 s able to releas
1e270 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f e the memory pro
1e280 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 perly and safely
1e290 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
1e2a0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 te3_get_table()
1e2b0 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 interface is imp
1e2c0 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 lemented as a wr
1e2d0 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 apper around.**
1e2e0 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d [sqlite3_exec()]
1e2f0 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 . The sqlite3_g
1e300 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 et_table() routi
1e310 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 ne does not have
1e320 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e access.** to an
1e330 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 y internal data
1e340 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 structures of SQ
1e350 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f Lite. It uses o
1e360 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a nly the public.*
1e370 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 * interface defi
1e380 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 ned here. As a
1e390 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 consequence, err
1e3a0 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 ors that occur i
1e3b0 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 n the.** wrapper
1e3c0 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f layer outside o
1e3d0 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b f the internal [
1e3e0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 sqlite3_exec()]
1e3f0 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 call are not.**
1e400 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 reflected in sub
1e410 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f sequent calls to
1e420 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 [sqlite3_errcod
1e430 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 e()] or.** [sqli
1e440 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a te3_errmsg()]..*
1e450 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
1e460 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
1e470 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c sqlite3_get_tabl
1e480 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 e(. sqlite3 *db
1e490 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e , /* An
1e4a0 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a open database *
1e4b0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
1e4c0 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c zSql, /* SQL
1e4d0 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 to be evaluated
1e4e0 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 */. char ***pa
1e4f0 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 zResult, /* R
1e500 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 esults of the qu
1e510 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e ery */. int *pn
1e520 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f Row, /
1e530 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 * Number of resu
1e540 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 lt rows written
1e550 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 here */. int *p
1e560 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 nColumn,
1e570 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 /* Number of res
1e580 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 ult columns writ
1e590 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 ten here */. ch
1e5a0 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 ar **pzErrmsg
1e5b0 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 /* Error msg
1e5c0 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f written here */
1e5d0 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 .);.SQLITE_API v
1e5e0 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 oid SQLITE_STDCA
1e5f0 4c 4c 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f LL sqlite3_free_
1e600 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 table(char **res
1e610 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ult);../*.** CAP
1e620 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 I3REF: Formatted
1e630 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 String Printing
1e640 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a Functions.**.**
1e650 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
1e660 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 are work-alikes
1e670 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 of the "printf()
1e680 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 " family of func
1e690 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 tions.** from th
1e6a0 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 e standard C lib
1e6b0 72 61 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72 rary..** These r
1e6c0 6f 75 74 69 6e 65 73 20 75 6e 64 65 72 73 74 61 outines understa
1e6d0 6e 64 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 63 nd most of the c
1e6e0 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d 61 74 ommon K&R format
1e6f0 74 69 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a ting options,.**
1e700 20 70 6c 75 73 20 73 6f 6d 65 20 61 64 64 69 74 plus some addit
1e710 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 ional non-standa
1e720 72 64 20 66 6f 72 6d 61 74 73 2c 20 64 65 74 61 rd formats, deta
1e730 69 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e iled below..** N
1e740 6f 74 65 20 74 68 61 74 20 73 6f 6d 65 20 6f 66 ote that some of
1e750 20 74 68 65 20 6d 6f 72 65 20 6f 62 73 63 75 72 the more obscur
1e760 65 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 e formatting opt
1e770 69 6f 6e 73 20 66 72 6f 6d 20 72 65 63 65 6e 74 ions from recent
1e780 0a 2a 2a 20 43 2d 6c 69 62 72 61 72 79 20 73 74 .** C-library st
1e790 61 6e 64 61 72 64 73 20 61 72 65 20 6f 6d 69 74 andards are omit
1e7a0 74 65 64 20 66 72 6f 6d 20 74 68 69 73 20 69 6d ted from this im
1e7b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a plementation..**
1e7c0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
1e7d0 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 _mprintf() and s
1e7e0 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 qlite3_vmprintf(
1e7f0 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 ) routines write
1e800 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 their.** result
1e810 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 s into memory ob
1e820 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c tained from [sql
1e830 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a ite3_malloc()]..
1e840 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 ** The strings r
1e850 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 eturned by these
1e860 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 two routines sh
1e870 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 ould be.** relea
1e880 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f sed by [sqlite3_
1e890 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 free()]. ^Both
1e8a0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
1e8b0 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 a.** NULL pointe
1e8c0 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 r if [sqlite3_ma
1e8d0 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c lloc()] is unabl
1e8e0 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e e to allocate en
1e8f0 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 ough.** memory t
1e900 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c o hold the resul
1e910 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a ting string..**.
1e920 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 ** ^(The sqlite3
1e930 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 _snprintf() rout
1e940 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 ine is similar t
1e950 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 o "snprintf()" f
1e960 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 rom.** the stand
1e970 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 ard C library.
1e980 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 The result is wr
1e990 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a itten into the.*
1e9a0 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 * buffer supplie
1e9b0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 d as the second
1e9c0 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 parameter whose
1e9d0 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 size is given by
1e9e0 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 .** the first pa
1e9f0 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 rameter. Note th
1ea00 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 at the order of
1ea10 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f the.** first two
1ea20 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 parameters is r
1ea30 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 eversed from snp
1ea40 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 rintf().)^ This
1ea50 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 is an.** histor
1ea60 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 ical accident th
1ea70 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 at cannot be fix
1ea80 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b ed without break
1ea90 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 ing.** backwards
1eaa0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 compatibility.
1eab0 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 ^(Note also tha
1eac0 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e t sqlite3_snprin
1ead0 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 tf().** returns
1eae0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 a pointer to its
1eaf0 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 buffer instead
1eb00 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 of the number of
1eb10 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 .** characters a
1eb20 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 ctually written
1eb30 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e into the buffer.
1eb40 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 )^ We admit tha
1eb50 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 t.** the number
1eb60 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 of characters wr
1eb70 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 itten would be a
1eb80 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 more useful ret
1eb90 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 urn.** value but
1eba0 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 we cannot chang
1ebb0 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 e the implementa
1ebc0 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f tion of sqlite3_
1ebd0 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f snprintf().** no
1ebe0 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 w without breaki
1ebf0 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 ng compatibility
1ec00 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 ..**.** ^As long
1ec10 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 as the buffer s
1ec20 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 ize is greater t
1ec30 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 han zero, sqlite
1ec40 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 3_snprintf().**
1ec50 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 guarantees that
1ec60 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c the buffer is al
1ec70 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e ways zero-termin
1ec80 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 ated. ^The firs
1ec90 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 t.** parameter "
1eca0 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 n" is the total
1ecb0 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 size of the buff
1ecc0 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 er, including sp
1ecd0 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a ace for.** the z
1ece0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 ero terminator.
1ecf0 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 So the longest
1ed00 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 string that can
1ed10 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a be completely.**
1ed20 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 written will be
1ed30 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e n-1 characters.
1ed40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
1ed50 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 te3_vsnprintf()
1ed60 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 routine is a var
1ed70 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 args version of
1ed80 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
1ed90 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ()..**.** These
1eda0 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 routines all imp
1edb0 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 lement some addi
1edc0 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e tional formattin
1edd0 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 g.** options tha
1ede0 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 t are useful for
1edf0 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 constructing SQ
1ee00 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a L statements..**
1ee10 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 All of the usua
1ee20 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 l printf() forma
1ee30 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 tting options ap
1ee40 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f ply. In additio
1ee50 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 n, there.** is a
1ee60 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 22 re "%q", "%Q", "
1ee70 25 77 22 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 %w" and "%z" opt
1ee80 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 ions..**.** ^(Th
1ee90 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b e %q option work
1eea0 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 s like %s in tha
1eeb0 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73 t it substitutes
1eec0 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 a nul-terminate
1eed0 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d d.** string from
1eee0 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 the argument li
1eef0 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f st. But %q also
1ef00 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 doubles every '
1ef10 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a \'' character..*
1ef20 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 * %q is designed
1ef30 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 for use inside
1ef40 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c a string literal
1ef50 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 .)^ By doubling
1ef60 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 each '\''.** ch
1ef70 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70 aracter it escap
1ef80 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65 es that characte
1ef90 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 r and allows it
1efa0 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 to be inserted i
1efb0 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e nto.** the strin
1efc0 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 g..**.** For exa
1efd0 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 mple, assume the
1efe0 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 string variable
1eff0 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 zText contains
1f000 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a text as follows:
1f010 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
1f020 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 te><pre>.** cha
1f030 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 r *zText = "It's
1f040 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a a happy day!";.
1f050 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
1f060 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 quote>.**.** One
1f070 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 can use this te
1f080 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 xt in an SQL sta
1f090 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 tement as follow
1f0a0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 s:.**.** <blockq
1f0b0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 uote><pre>.** c
1f0c0 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 har *zSQL = sqli
1f0d0 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 te3_mprintf("INS
1f0e0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 ERT INTO table V
1f0f0 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 ALUES('%q')", zT
1f100 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 ext);.** sqlite
1f110 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 3_exec(db, zSQL,
1f120 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 0, 0, 0);.** s
1f130 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c qlite3_free(zSQL
1f140 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c );.** </pre></bl
1f150 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 ockquote>.**.**
1f160 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 Because the %q f
1f170 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 ormat string is
1f180 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 used, the '\'' c
1f190 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 haracter in zTex
1f1a0 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 t.** is escaped
1f1b0 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 and the SQL gene
1f1c0 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c rated is as foll
1f1d0 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 ows:.**.** <bloc
1f1e0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 kquote><pre>.**
1f1f0 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 INSERT INTO tab
1f200 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 le1 VALUES('It''
1f210 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 s a happy day!')
1f220 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
1f230 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 kquote>.**.** Th
1f240 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 is is correct.
1f250 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 Had we used %s i
1f260 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 nstead of %q, th
1f270 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a e generated SQL.
1f280 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f ** would have lo
1f290 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a oked like this:.
1f2a0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
1f2b0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 e><pre>.** INSE
1f2c0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 RT INTO table1 V
1f2d0 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 ALUES('It's a ha
1f2e0 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c ppy day!');.** <
1f2f0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
1f300 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 e>.**.** This se
1f310 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 cond example is
1f320 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 an SQL syntax er
1f330 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 ror. As a gener
1f340 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 al rule you shou
1f350 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 ld.** always use
1f360 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 %q instead of %
1f370 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 s when inserting
1f380 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 text into a str
1f390 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a ing literal..**.
1f3a0 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 ** ^(The %Q opti
1f3b0 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 on works like %q
1f3c0 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 except it also
1f3d0 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 adds single quot
1f3e0 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 es around.** the
1f3f0 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 outside of the
1f400 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 total string. A
1f410 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 dditionally, if
1f420 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e the parameter in
1f430 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 the.** argument
1f440 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 list is a NULL
1f450 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 pointer, %Q subs
1f460 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74 titutes the text
1f470 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 "NULL" (without
1f480 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 .** single quote
1f490 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 s).)^ So, for e
1f4a0 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c xample, one coul
1f4b0 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c d say:.**.** <bl
1f4c0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
1f4d0 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 * char *zSQL =
1f4e0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 sqlite3_mprintf(
1f4f0 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 "INSERT INTO tab
1f500 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 le VALUES(%Q)",
1f510 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 zText);.** sqli
1f520 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 te3_exec(db, zSQ
1f530 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 L, 0, 0, 0);.**
1f540 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 sqlite3_free(zS
1f550 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f QL);.** </pre></
1f560 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a blockquote>.**.*
1f570 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 * The code above
1f580 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 will render a c
1f590 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 orrect SQL state
1f5a0 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c ment in the zSQL
1f5b0 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 .** variable eve
1f5c0 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 n if the zText v
1f5d0 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c ariable is a NUL
1f5e0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a L pointer..**.**
1f5f0 20 5e 28 54 68 65 20 22 25 77 22 20 66 6f 72 6d ^(The "%w" form
1f600 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 atting option is
1f610 20 6c 69 6b 65 20 22 25 71 22 20 65 78 63 65 70 like "%q" excep
1f620 74 20 74 68 61 74 20 69 74 20 65 78 70 65 63 74 t that it expect
1f630 73 20 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74 61 s to.** be conta
1f640 69 6e 65 64 20 77 69 74 68 69 6e 20 64 6f 75 62 ined within doub
1f650 6c 65 2d 71 75 6f 74 65 73 20 69 6e 73 74 65 61 le-quotes instea
1f660 64 20 6f 66 20 73 69 6e 67 6c 65 20 71 75 6f 74 d of single quot
1f670 65 73 2c 20 61 6e 64 20 69 74 0a 2a 2a 20 65 73 es, and it.** es
1f680 63 61 70 65 73 20 74 68 65 20 64 6f 75 62 6c 65 capes the double
1f690 2d 71 75 6f 74 65 20 63 68 61 72 61 63 74 65 72 -quote character
1f6a0 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 instead of the
1f6b0 73 69 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20 single-quote.**
1f6c0 63 68 61 72 61 63 74 65 72 2e 29 5e 20 20 54 68 character.)^ Th
1f6d0 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e e "%w" formattin
1f6e0 67 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 74 65 g option is inte
1f6f0 6e 64 65 64 20 66 6f 72 20 73 61 66 65 6c 79 20 nded for safely
1f700 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 61 62 inserting.** tab
1f710 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61 le and column na
1f720 6d 65 73 20 69 6e 74 6f 20 61 20 63 6f 6e 73 74 mes into a const
1f730 72 75 63 74 65 64 20 53 51 4c 20 73 74 61 74 65 ructed SQL state
1f740 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 ment..**.** ^(Th
1f750 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e e "%z" formattin
1f760 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c g option works l
1f770 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74 ike "%s" but wit
1f780 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f h the.** additio
1f790 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65 n that after the
1f7a0 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e string has been
1f7b0 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 read and copied
1f7c0 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 into.** the res
1f7d0 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 ult, [sqlite3_fr
1f7e0 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 ee()] is called
1f7f0 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 on the input str
1f800 69 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 ing.)^.*/.SQLITE
1f810 5f 41 50 49 20 63 68 61 72 20 2a 53 51 4c 49 54 _API char *SQLIT
1f820 45 5f 43 44 45 43 4c 20 73 71 6c 69 74 65 33 5f E_CDECL sqlite3_
1f830 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 mprintf(const ch
1f840 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 ar*,...);.SQLITE
1f850 5f 41 50 49 20 63 68 61 72 20 2a 53 51 4c 49 54 _API char *SQLIT
1f860 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
1f870 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 3_vmprintf(const
1f880 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 char*, va_list)
1f890 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 ;.SQLITE_API cha
1f8a0 72 20 2a 53 51 4c 49 54 45 5f 43 44 45 43 4c 20 r *SQLITE_CDECL
1f8b0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
1f8c0 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 (int,char*,const
1f8d0 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 char*, ...);.SQ
1f8e0 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 53 LITE_API char *S
1f8f0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
1f900 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 lite3_vsnprintf(
1f910 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 int,char*,const
1f920 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b char*, va_list);
1f930 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1f940 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 : Memory Allocat
1f950 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a ion Subsystem.**
1f960 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 .** The SQLite c
1f970 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74 ore uses these t
1f980 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f hree routines fo
1f990 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e r all of its own
1f9a0 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d .** internal mem
1f9b0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e ory allocation n
1f9c0 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 eeds. "Core" in
1f9d0 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e the previous sen
1f9e0 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f tence.** does no
1f9f0 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 t include operat
1fa00 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 ing-system speci
1fa10 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e fic VFS implemen
1fa20 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 tation. The.**
1fa30 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 Windows VFS uses
1fa40 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 native malloc()
1fa50 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 and free() for
1fa60 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e some operations.
1fa70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
1fa80 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 te3_malloc() rou
1fa90 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 tine returns a p
1faa0 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 ointer to a bloc
1fab0 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 k.** of memory a
1fac0 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 t least N bytes
1fad0 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 in length, where
1fae0 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 N is the parame
1faf0 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 ter..** ^If sqli
1fb00 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 te3_malloc() is
1fb10 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e unable to obtain
1fb20 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 sufficient free
1fb30 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 .** memory, it r
1fb40 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f eturns a NULL po
1fb50 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 inter. ^If the
1fb60 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a parameter N to.*
1fb70 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 * sqlite3_malloc
1fb80 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 () is zero or ne
1fb90 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 gative then sqli
1fba0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 te3_malloc() ret
1fbb0 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 urns.** a NULL p
1fbc0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ointer..**.** ^T
1fbd0 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f he sqlite3_mallo
1fbe0 63 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 c64(N) routine w
1fbf0 6f 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a orks just like.*
1fc00 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 * sqlite3_malloc
1fc10 28 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20 (N) except that
1fc20 4e 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 N is an unsigned
1fc30 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 64-bit integer
1fc40 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 instead.** of a
1fc50 73 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e signed 32-bit in
1fc60 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 teger..**.** ^Ca
1fc70 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 lling sqlite3_fr
1fc80 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e ee() with a poin
1fc90 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 ter previously r
1fca0 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 eturned.** by sq
1fcb0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f lite3_malloc() o
1fcc0 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f r sqlite3_reallo
1fcd0 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 c() releases tha
1fce0 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 t memory so.** t
1fcf0 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 hat it might be
1fd00 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 reused. ^The sq
1fd10 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 lite3_free() rou
1fd20 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d tine is.** a no-
1fd30 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 op if is called
1fd40 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e with a NULL poin
1fd50 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 ter. Passing a
1fd60 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 NULL pointer.**
1fd70 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 to sqlite3_free(
1fd80 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 ) is harmless.
1fd90 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 After being free
1fda0 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f d, memory.** sho
1fdb0 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 uld neither be r
1fdc0 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e ead nor written.
1fdd0 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 Even reading p
1fde0 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a reviously freed.
1fdf0 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 ** memory might
1fe00 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d result in a segm
1fe10 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f entation fault o
1fe20 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 r other severe e
1fe30 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 rror..** Memory
1fe40 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 corruption, a se
1fe50 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 gmentation fault
1fe60 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 , or other sever
1fe70 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 e error.** might
1fe80 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 result if sqlit
1fe90 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c e3_free() is cal
1fea0 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e led with a non-N
1feb0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 ULL pointer that
1fec0 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 .** was not obta
1fed0 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 ined from sqlite
1fee0 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 3_malloc() or sq
1fef0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e lite3_realloc().
1ff00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
1ff10 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 te3_realloc(X,N)
1ff20 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d interface attem
1ff30 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a pts to resize a.
1ff40 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 ** prior memory
1ff50 61 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 allocation X to
1ff60 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 be at least N by
1ff70 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 tes..** ^If the
1ff80 58 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 X parameter to s
1ff90 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 qlite3_realloc(X
1ffa0 2c 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c ,N).** is a NULL
1ffb0 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 pointer then it
1ffc0 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 s behavior is id
1ffd0 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 entical to calli
1ffe0 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 ng.** sqlite3_ma
1fff0 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 lloc(N)..** ^If
20000 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 the N parameter
20010 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c to sqlite3_reall
20020 6f 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 oc(X,N) is zero
20030 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 or.** negative t
20040 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 hen the behavior
20050 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 is exactly the
20060 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a same as calling.
20070 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 ** sqlite3_free(
20080 58 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f X)..** ^sqlite3_
20090 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 realloc(X,N) ret
200a0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
200b0 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 o a memory alloc
200c0 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c ation.** of at l
200d0 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 east N bytes in
200e0 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 size or NULL if
200f0 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d insufficient mem
20100 6f 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65 ory is available
20110 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 ..** ^If M is th
20120 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 e size of the pr
20130 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 ior allocation,
20140 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 then min(N,M) by
20150 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 tes.** of the pr
20160 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 ior allocation a
20170 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 re copied into t
20180 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 he beginning of
20190 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a buffer returned.
201a0 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 ** by sqlite3_re
201b0 61 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 alloc(X,N) and t
201c0 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 he prior allocat
201d0 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a ion is freed..**
201e0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 ^If sqlite3_rea
201f0 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e lloc(X,N) return
20200 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 s NULL and N is
20210 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74 positive, then t
20220 68 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f he.** prior allo
20230 63 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 cation is not fr
20240 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 eed..**.** ^The
20250 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 sqlite3_realloc6
20260 34 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 4(X,N) interface
20270 73 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 s works the same
20280 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 as.** sqlite3_r
20290 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 ealloc(X,N) exce
202a0 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 20 36 pt that N is a 6
202b0 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 4-bit unsigned i
202c0 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a nteger instead.*
202d0 2a 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 * of a 32-bit si
202e0 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a gned integer..**
202f0 0a 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d .** ^If X is a m
20300 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
20310 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 previously obta
20320 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 ined from sqlite
20330 33 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 3_malloc(),.** s
20340 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 qlite3_malloc64(
20350 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c ), sqlite3_reall
20360 6f 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 oc(), or sqlite3
20370 5f 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 _realloc64(), th
20380 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 en.** sqlite3_ms
20390 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 74 ize(X) returns t
203a0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20 he size of that
203b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
203c0 6e 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e n in bytes..** ^
203d0 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e The value return
203e0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 ed by sqlite3_ms
203f0 69 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65 20 ize(X) might be
20400 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 larger than the
20410 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 number.** of byt
20420 65 73 20 72 65 71 75 65 73 74 65 64 20 77 68 65 es requested whe
20430 6e 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 n X was allocate
20440 64 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e d. ^If X is a N
20450 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e ULL pointer then
20460 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a .** sqlite3_msiz
20470 65 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72 e(X) returns zer
20480 6f 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20 o. If X points
20490 74 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 to something tha
204a0 74 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 t is not.** the
204b0 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d beginning of mem
204c0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 ory allocation,
204d0 6f 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20 or if it points
204e0 74 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a to a formerly.**
204f0 20 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c valid memory al
20500 6c 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61 location that ha
20510 73 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64 s now been freed
20520 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 , then the behav
20530 69 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 ior.** of sqlite
20540 33 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e 3_msize(X) is un
20550 64 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 defined and poss
20560 69 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a ibly harmful..**
20570 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 .** ^The memory
20580 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 returned by sqli
20590 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 te3_malloc(), sq
205a0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c lite3_realloc(),
205b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c .** sqlite3_mall
205c0 6f 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 oc64(), and sqli
205d0 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a te3_realloc64().
205e0 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 ** is always ali
205f0 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 gned to at least
20600 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 an 8 byte bound
20610 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 ary, or to a.**
20620 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 4 byte boundary
20630 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 if the [SQLITE_4
20640 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 _BYTE_ALIGNED_MA
20650 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 LLOC] compile-ti
20660 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 me.** option is
20670 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 used..**.** In S
20680 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e QLite version 3.
20690 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 5.0 and 3.5.1, i
206a0 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 t was possible t
206b0 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 o define.** the
206c0 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f SQLITE_OMIT_MEMO
206d0 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 RY_ALLOCATION wh
206e0 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 ich would cause
206f0 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 the built-in.**
20700 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
20710 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
20720 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 to be omitted.
20730 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 That capability
20740 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 .** is no longer
20750 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 provided. Only
20760 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 built-in memory
20770 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 allocators can
20780 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 be used..**.** P
20790 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 rior to SQLite v
207a0 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 ersion 3.7.10, t
207b0 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e he Windows OS in
207c0 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 terface layer ca
207d0 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 lled.** the syst
207e0 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 em malloc() and
207f0 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 free() directly
20800 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a when converting.
20810 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 ** filenames bet
20820 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 ween the UTF-8 e
20830 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 ncoding used by
20840 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 SQLite.** and wh
20850 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 atever filename
20860 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 encoding is used
20870 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c by the particul
20880 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e ar Windows.** in
20890 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d stallation. Mem
208a0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 ory allocation e
208b0 72 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 rrors were detec
208c0 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 ted, but.** they
208d0 20 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 were reported b
208e0 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 ack as [SQLITE_C
208f0 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b ANTOPEN] or.** [
20900 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 SQLITE_IOERR] ra
20910 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 ther than [SQLIT
20920 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 E_NOMEM]..**.**
20930 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 The pointer argu
20940 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 ments to [sqlite
20950 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 3_free()] and [s
20960 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
20970 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 ].** must be eit
20980 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 her NULL or else
20990 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e pointers obtain
209a0 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a ed from a prior.
209b0 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 ** invocation of
209c0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
209d0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
209e0 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 realloc()] that
209f0 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 have.** not yet
20a00 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a been released..*
20a10 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 *.** The applica
20a20 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 tion must not re
20a30 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 ad or write any
20a40 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f part of.** a blo
20a50 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 ck of memory aft
20a60 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 er it has been r
20a70 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a eleased using.**
20a80 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
20a90 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 ] or [sqlite3_re
20aa0 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c alloc()]..*/.SQL
20ab0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 ITE_API void *SQ
20ac0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
20ad0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 ite3_malloc(int)
20ae0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 ;.SQLITE_API voi
20af0 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c d *SQLITE_STDCAL
20b00 4c 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 L sqlite3_malloc
20b10 36 34 28 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 64(sqlite3_uint6
20b20 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 4);.SQLITE_API v
20b30 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 oid *SQLITE_STDC
20b40 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c ALL sqlite3_real
20b50 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b loc(void*, int);
20b60 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
20b70 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c *SQLITE_STDCALL
20b80 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
20b90 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 64(void*, sqlite
20ba0 33 5f 75 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 3_uint64);.SQLIT
20bb0 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 E_API void SQLIT
20bc0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
20bd0 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 53 3_free(void*);.S
20be0 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 QLITE_API sqlite
20bf0 33 5f 75 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 3_uint64 SQLITE_
20c00 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
20c10 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f msize(void*);../
20c20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d *.** CAPI3REF: M
20c30 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 emory Allocator
20c40 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a Statistics.**.**
20c50 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 SQLite provides
20c60 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 these two inter
20c70 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 faces for report
20c80 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 ing on the statu
20c90 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c s.** of the [sql
20ca0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 ite3_malloc()],
20cb0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
20cc0 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 , and [sqlite3_r
20cd0 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 ealloc()].** rou
20ce0 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 tines, which for
20cf0 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d m the built-in m
20d00 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
20d10 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a subsystem..**.*
20d20 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f * ^The [sqlite3_
20d30 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 memory_used()] r
20d40 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 outine returns t
20d50 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
20d60 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 es.** of memory
20d70 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 currently outsta
20d80 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 nding (malloced
20d90 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a but not freed)..
20da0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 ** ^The [sqlite3
20db0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 _memory_highwate
20dc0 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 r()] routine ret
20dd0 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d urns the maximum
20de0 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 .** value of [sq
20df0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 lite3_memory_use
20e00 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 d()] since the h
20e10 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a igh-water mark.*
20e20 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 * was last reset
20e30 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 . ^The values r
20e40 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 eturned by [sqli
20e50 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 te3_memory_used(
20e60 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 )] and.** [sqlit
20e70 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 e3_memory_highwa
20e80 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 ter()] include a
20e90 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 ny overhead.** a
20ea0 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 dded by SQLite i
20eb0 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 n its implementa
20ec0 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 tion of [sqlite3
20ed0 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 _malloc()],.** b
20ee0 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 ut not overhead
20ef0 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 added by the any
20f00 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 underlying syst
20f10 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f em library.** ro
20f20 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c utines that [sql
20f30 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d ite3_malloc()] m
20f40 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e ay call..**.** ^
20f50 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d The memory high-
20f60 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 water mark is re
20f70 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 set to the curre
20f80 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b nt value of.** [
20f90 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 sqlite3_memory_u
20fa0 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e sed()] if and on
20fb0 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 ly if the parame
20fc0 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 ter to.** [sqlit
20fd0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 e3_memory_highwa
20fe0 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 ter()] is true.
20ff0 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 ^The value retu
21000 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 rned.** by [sqli
21010 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 te3_memory_highw
21020 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 ater(1)] is the
21030 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a high-water mark.
21040 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 ** prior to the
21050 72 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 reset..*/.SQLITE
21060 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 _API sqlite3_int
21070 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 64 SQLITE_STDCAL
21080 4c 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 L sqlite3_memory
21090 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 53 51 4c _used(void);.SQL
210a0 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f ITE_API sqlite3_
210b0 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 54 44 int64 SQLITE_STD
210c0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 65 6d CALL sqlite3_mem
210d0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e ory_highwater(in
210e0 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f t resetFlag);../
210f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 *.** CAPI3REF: P
21100 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d seudo-Random Num
21110 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a ber Generator.**
21120 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 .** SQLite conta
21130 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 ins a high-quali
21140 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d ty pseudo-random
21150 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f number generato
21160 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f r (PRNG) used to
21170 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f .** select rando
21180 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 m [ROWID | ROWID
21190 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e s] when insertin
211a0 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e g new records in
211b0 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a to a table that.
211c0 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 ** already uses
211d0 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 the largest poss
211e0 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 ible [ROWID]. T
211f0 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 he PRNG is also
21200 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 used for.** the
21210 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 build-in random(
21220 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 ) and randomblob
21230 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 () SQL functions
21240 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 . This interfac
21250 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c e allows.** appl
21260 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 ications to acce
21270 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 ss the same PRNG
21280 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f for other purpo
21290 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 ses..**.** ^A ca
212a0 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 ll to this routi
212b0 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 ne stores N byte
212c0 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 s of randomness
212d0 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a into buffer P..*
212e0 2a 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74 * ^The P paramet
212f0 65 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c er can be a NULL
21300 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 pointer..**.**
21310 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 ^If this routine
21320 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 has not been pr
21330 65 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 eviously called
21340 6f 72 20 69 66 20 74 68 65 20 70 72 65 76 69 6f or if the previo
21350 75 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e us.** call had N
21360 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f less than one o
21370 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 r a NULL pointer
21380 20 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65 for P, then the
21390 20 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 PRNG is.** seed
213a0 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e ed using randomn
213b0 65 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f ess obtained fro
213c0 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 m the xRandomnes
213d0 73 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 s method of.** t
213e0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 he default [sqli
213f0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e te3_vfs] object.
21400 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76 .** ^If the prev
21410 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 ious call to thi
21420 73 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e s routine had an
21430 20 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 N of 1 or more
21440 61 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c and a.** non-NUL
21450 4c 20 50 20 74 68 65 6e 20 74 68 65 20 70 73 65 L P then the pse
21460 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 udo-randomness i
21470 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 s generated.** i
21480 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 nternally and wi
21490 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 thout recourse t
214a0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 o the [sqlite3_v
214b0 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a fs] xRandomness.
214c0 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 ** method..*/.SQ
214d0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 LITE_API void SQ
214e0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
214f0 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 ite3_randomness(
21500 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b int N, void *P);
21510 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
21520 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 : Compile-Time A
21530 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c uthorization Cal
21540 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 lbacks.** METHOD
21550 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 : sqlite3.**.**
21560 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 ^This routine re
21570 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f gisters an autho
21580 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 rizer callback w
21590 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 ith a particular
215a0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
215b0 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c nnection], suppl
215c0 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 ied in the first
215d0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 argument..** ^T
215e0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
215f0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
21600 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 d as SQL stateme
21610 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f nts are being co
21620 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 mpiled.** by [sq
21630 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d lite3_prepare()]
21640 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 or its variants
21650 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
21660 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c e_v2()],.** [sql
21670 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 ite3_prepare16()
21680 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 ] and [sqlite3_p
21690 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 repare16_v2()].
216a0 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 ^At various.**
216b0 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 points during th
216c0 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 e compilation pr
216d0 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 ocess, as logic
216e0 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 is being created
216f0 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 .** to perform v
21700 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 arious actions,
21710 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 the authorizer c
21720 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b allback is invok
21730 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 ed to.** see if
21740 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 those actions ar
21750 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 e allowed. ^The
21760 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
21770 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 back should.** r
21780 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b eturn [SQLITE_OK
21790 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 ] to allow the a
217a0 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 ction, [SQLITE_I
217b0 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c GNORE] to disall
217c0 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 ow the.** specif
217d0 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c ic action but al
217e0 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 low the SQL stat
217f0 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 ement to continu
21800 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 e to be.** compi
21810 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f led, or [SQLITE_
21820 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 DENY] to cause t
21830 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 he entire SQL st
21840 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a atement to be.**
21850 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 rejected with a
21860 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 n error. ^If th
21870 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
21880 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a lback returns.**
21890 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 any value other
218a0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 than [SQLITE_IG
218b0 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f NORE], [SQLITE_O
218c0 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 K], or [SQLITE_D
218d0 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 ENY].** then the
218e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
218f0 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 e_v2()] or equiv
21900 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 alent call that
21910 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 triggered.** the
21920 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c authorizer will
21930 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 fail with an er
21940 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a ror message..**.
21950 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c ** When the call
21960 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 back returns [SQ
21970 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d LITE_OK], that m
21980 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 eans the operati
21990 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 on.** requested
219a0 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 is ok. ^When th
219b0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 e callback retur
219c0 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d ns [SQLITE_DENY]
219d0 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 , the.** [sqlite
219e0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
219f0 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 or equivalent ca
21a00 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 ll that triggere
21a10 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 d the.** authori
21a20 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 zer will fail wi
21a30 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 th an error mess
21a40 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 age explaining t
21a50 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 hat.** access is
21a60 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 denied. .**.**
21a70 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d ^The first param
21a80 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 eter to the auth
21a90 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
21aa0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 is a copy of the
21ab0 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 third.** parame
21ac0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ter to the sqlit
21ad0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 e3_set_authorize
21ae0 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e r() interface. ^
21af0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
21b00 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 eter.** to the c
21b10 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e allback is an in
21b20 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f teger [SQLITE_CO
21b30 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 PY | action code
21b40 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 ] that specifies
21b50 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c .** the particul
21b60 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 ar action to be
21b70 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 authorized. ^The
21b80 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 third through s
21b90 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a ixth parameters.
21ba0 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 ** to the callba
21bb0 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d ck are zero-term
21bc0 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 inated strings t
21bd0 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 hat contain addi
21be0 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c tional.** detail
21bf0 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 s about the acti
21c00 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 on to be authori
21c10 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 zed..**.** ^If t
21c20 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 he action code i
21c30 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a s [SQLITE_READ].
21c40 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 ** and the callb
21c50 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c ack returns [SQL
21c60 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e ITE_IGNORE] then
21c70 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 the.** [prepare
21c80 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 d statement] sta
21c90 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 tement is constr
21ca0 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 ucted to substit
21cb0 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 ute.** a NULL va
21cc0 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 lue in place of
21cd0 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e the table column
21ce0 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 that would have
21cf0 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 .** been read if
21d00 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 [SQLITE_OK] had
21d10 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 been returned.
21d20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e The [SQLITE_IGN
21d30 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 ORE].** return c
21d40 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 an be used to de
21d50 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 ny an untrusted
21d60 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 user access to i
21d70 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c ndividual.** col
21d80 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e umns of a table.
21d90 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 .** ^If the acti
21da0 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 on code is [SQLI
21db0 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 TE_DELETE] and t
21dc0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 he callback retu
21dd0 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 rns.** [SQLITE_I
21de0 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 GNORE] then the
21df0 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 [DELETE] operati
21e00 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 on proceeds but
21e10 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 the.** [truncate
21e20 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 optimization] i
21e30 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 s disabled and a
21e40 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 ll rows are dele
21e50 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 ted individually
21e60 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f ..**.** An autho
21e70 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 rizer is used wh
21e80 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 en [sqlite3_prep
21e90 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d are | preparing]
21ea0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e .** SQL statemen
21eb0 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 ts from an untru
21ec0 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 sted source, to
21ed0 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 ensure that the
21ee0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a SQL statements.*
21ef0 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 * do not try to
21f00 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79 access data they
21f10 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 are not allowed
21f20 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 to see, or that
21f30 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 they do not.**
21f40 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d try to execute m
21f50 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 alicious stateme
21f60 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 nts that damage
21f70 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 the database. F
21f80 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 or.** example, a
21f90 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 n application ma
21fa0 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 y allow a user t
21fb0 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 o enter arbitrar
21fc0 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 y.** SQL queries
21fd0 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 for evaluation
21fe0 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 by a database.
21ff0 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 But the applicat
22000 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 ion does.** not
22010 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f want the user to
22020 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 be able to make
22030 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 arbitrary chang
22040 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 es to the.** dat
22050 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f abase. An autho
22060 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e rizer could then
22070 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 be put in place
22080 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 while the.** us
22090 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 er-entered SQL i
220a0 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 s being [sqlite3
220b0 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 _prepare | prepa
220c0 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 red] that.** dis
220d0 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e allows everythin
220e0 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 g except [SELECT
220f0 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a ] statements..**
22100 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 .** Applications
22110 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 that need to pr
22120 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 ocess SQL from u
22130 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 ntrusted sources
22140 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 .** might also c
22150 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 onsider lowering
22160 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 resource limits
22170 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
22180 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 limit()].** and
22190 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 limiting databas
221a0 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 e size using the
221b0 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 [max_page_count
221c0 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e ] [PRAGMA].** in
221d0 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 addition to usi
221e0 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 ng an authorizer
221f0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 ..**.** ^(Only a
22200 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a single authoriz
22210 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 er can be in pla
22220 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 ce on a database
22230 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 connection.** a
22240 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 t a time. Each
22250 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
22260 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f set_authorizer o
22270 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 verrides the.**
22280 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e previous call.)^
22290 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 ^Disable the a
222a0 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 uthorizer by ins
222b0 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 talling a NULL c
222c0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 allback..** The
222d0 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 authorizer is di
222e0 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c sabled by defaul
222f0 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 t..**.** The aut
22300 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
22310 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 must not do any
22320 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 thing that will
22330 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 modify.** the da
22340 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
22350 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 n that invoked t
22360 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
22370 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 llback..** Note
22380 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 that [sqlite3_pr
22390 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 epare_v2()] and
223a0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
223b0 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 both modify the
223c0 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 ir.** database c
223d0 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 onnections for t
223e0 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d he meaning of "m
223f0 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 odify" in this p
22400 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 aragraph..**.**
22410 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 ^When [sqlite3_p
22420 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 repare_v2()] is
22430 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 used to prepare
22440 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 a statement, the
22450 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 .** statement mi
22460 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 ght be re-prepar
22470 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 ed during [sqlit
22480 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 e3_step()] due t
22490 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 o a .** schema c
224a0 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 hange. Hence, t
224b0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 he application s
224c0 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 hould ensure tha
224d0 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 t the.** correct
224e0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
224f0 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 back remains in
22500 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 place during the
22510 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
22520 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 ]..**.** ^Note t
22530 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a hat the authoriz
22540 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 er callback is i
22550 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 nvoked only duri
22560 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 ng.** [sqlite3_p
22570 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 repare()] or its
22580 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 variants. Auth
22590 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 orization is not
225a0 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 .** performed du
225b0 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 ring statement e
225c0 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 valuation in [sq
225d0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 lite3_step()], u
225e0 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 nless.** as stat
225f0 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f ed in the previo
22600 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 us paragraph, sq
22610 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 lite3_step() inv
22620 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f okes.** sqlite3_
22630 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 prepare_v2() to
22640 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74 reprepare a stat
22650 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 ement after a sc
22660 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a hema change..*/.
22670 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
22680 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
22690 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 lite3_set_author
226a0 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a izer(. sqlite3*
226b0 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 ,. int (*xAuth)
226c0 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 (void*,int,const
226d0 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 char*,const cha
226e0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 r*,const char*,c
226f0 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 onst char*),. v
22700 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 oid *pUserData.)
22710 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
22720 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 F: Authorizer Re
22730 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a turn Codes.**.**
22740 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 The [sqlite3_se
22750 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 t_authorizer | a
22760 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
22770 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 ck function] mus
22780 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 t.** return eith
22790 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f er [SQLITE_OK] o
227a0 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 r one of these t
227b0 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 wo constants in
227c0 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e order.** to sign
227d0 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 al SQLite whethe
227e0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 r or not the act
227f0 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 ion is permitted
22800 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 . See the.** [s
22810 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
22820 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a rizer | authoriz
22830 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e er documentation
22840 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c ] for additional
22850 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e .** information.
22860 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 .**.** Note that
22870 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 SQLITE_IGNORE i
22880 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61 s also used as a
22890 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c [conflict resol
228a0 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72 ution mode].** r
228b0 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68 65 eturned from the
228c0 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f [sqlite3_vtab_o
228d0 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e n_conflict()] in
228e0 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 terface..*/.#def
228f0 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 ine SQLITE_DENY
22900 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 1 /* Abort t
22910 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
22920 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a with an error *
22930 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
22940 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 _IGNORE 2 /* D
22950 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 on't allow acces
22960 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e s, but don't gen
22970 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a erate an error *
22980 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 /../*.** CAPI3RE
22990 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 F: Authorizer Ac
229a0 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a tion Codes.**.**
229b0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 The [sqlite3_se
229c0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 t_authorizer()]
229d0 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 interface regist
229e0 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 ers a callback f
229f0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 unction.** that
22a00 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 is invoked to au
22a10 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 thorize certain
22a20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 SQL statement ac
22a30 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 tions. The.** s
22a40 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
22a50 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 to the callback
22a60 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f is an integer co
22a70 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 de that specifie
22a80 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e s.** what action
22a90 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 is being author
22aa0 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 ized. These are
22ab0 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 the integer act
22ac0 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a ion codes that.*
22ad0 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 * the authorizer
22ae0 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 callback may be
22af0 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 passed..**.** T
22b00 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 hese action code
22b10 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 values signify
22b20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 what kind of ope
22b30 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a ration is to be.
22b40 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 ** authorized.
22b50 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 The 3rd and 4th
22b60 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 parameters to th
22b70 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a e authorization.
22b80 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 ** callback func
22b90 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 tion will be par
22ba0 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 ameters or NULL
22bb0 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 depending on whi
22bc0 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 ch of these.** c
22bd0 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 odes is used as
22be0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d the second param
22bf0 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 eter. ^(The 5th
22c00 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
22c10 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 e.** authorizer
22c20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 callback is the
22c30 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 name of the data
22c40 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 base ("main", "t
22c50 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 emp",.** etc.) i
22c60 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 f applicable.)^
22c70 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 ^The 6th parame
22c80 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f ter to the autho
22c90 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a rizer callback.*
22ca0 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 * is the name of
22cb0 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 the inner-most
22cc0 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 trigger or view
22cd0 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 that is responsi
22ce0 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 ble for.** the a
22cf0 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 ccess attempt or
22d00 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 NULL if this ac
22d10 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 cess attempt is
22d20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a directly from.**
22d30 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 top-level SQL c
22d40 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a ode..*/./*******
22d50 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
22d60 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
22d70 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a **** 3rd *******
22d80 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a ***** 4th ******
22d90 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 *****/.#define S
22da0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 QLITE_CREATE_IND
22db0 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20 EX 1
22dc0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 /* Index Name
22dd0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
22de0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
22df0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c LITE_CREATE_TABL
22e00 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f E 2 /
22e10 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
22e20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
22e30 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
22e40 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f ITE_CREATE_TEMP_
22e50 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a INDEX 3 /*
22e60 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 Index Name
22e70 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
22e80 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
22e90 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 TE_CREATE_TEMP_T
22ea0 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 ABLE 4 /*
22eb0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
22ec0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
22ed0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
22ee0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 E_CREATE_TEMP_TR
22ef0 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 IGGER 5 /* T
22f00 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 rigger Name T
22f10 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
22f20 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
22f30 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 _CREATE_TEMP_VIE
22f40 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 W 6 /* Vi
22f50 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 ew Name NU
22f60 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
22f70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
22f80 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 CREATE_TRIGGER
22f90 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 7 /* Tri
22fa0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 gger Name Tab
22fb0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
22fc0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
22fd0 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 REATE_VIEW
22fe0 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 8 /* View
22ff0 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c Name NULL
23000 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
23010 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 define SQLITE_DE
23020 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 LETE
23030 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 9 /* Table
23040 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
23050 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
23060 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
23070 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 P_INDEX
23080 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 10 /* Index
23090 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 Name Table
230a0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
230b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
230c0 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 _TABLE
230d0 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 11 /* Table N
230e0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
230f0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
23100 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
23110 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 TEMP_INDEX
23120 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 12 /* Index Na
23130 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 me Table Na
23140 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
23150 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 ne SQLITE_DROP_T
23160 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 EMP_TABLE 1
23170 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 3 /* Table Nam
23180 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
23190 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
231a0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 e SQLITE_DROP_TE
231b0 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 MP_TRIGGER 14
231c0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 /* Trigger Na
231d0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 me Table Name
231e0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
231f0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d SQLITE_DROP_TEM
23200 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20 P_VIEW 15
23210 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 /* View Name
23220 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
23230 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
23240 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 SQLITE_DROP_TRIG
23250 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20 GER 16
23260 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 /* Trigger Name
23270 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
23280 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
23290 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 QLITE_DROP_VIEW
232a0 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20 17
232b0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 /* View Name
232c0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
232d0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
232e0 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 LITE_INSERT
232f0 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 18 /
23300 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
23310 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
23320 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
23330 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 ITE_PRAGMA
23340 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 19 /*
23350 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 Pragma Name
23360 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 1st arg or NULL
23370 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
23380 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 TE_READ
23390 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 20 /*
233a0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
233b0 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 Column Name
233c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
233d0 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 E_SELECT
233e0 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 21 /* N
233f0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e ULL N
23400 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
23410 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
23420 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 _TRANSACTION
23430 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 22 /* Op
23440 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 eration NU
23450 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
23460 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
23470 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20 UPDATE
23480 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 23 /* Tab
23490 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c le Name Col
234a0 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a umn Name */.
234b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
234c0 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 TTACH
234d0 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 24 /* File
234e0 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c name NULL
234f0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
23500 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 define SQLITE_DE
23510 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 TACH
23520 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 25 /* Datab
23530 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 ase Name NULL
23540 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
23550 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 efine SQLITE_ALT
23560 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 ER_TABLE
23570 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 26 /* Databa
23580 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 se Name Table
23590 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
235a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e fine SQLITE_REIN
235b0 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20 DEX
235c0 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 27 /* Index N
235d0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
235e0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
235f0 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 ine SQLITE_ANALY
23600 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ZE
23610 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 28 /* Table Na
23620 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
23630 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
23640 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
23650 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 _VTABLE 2
23660 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 9 /* Table Nam
23670 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 e Module Na
23680 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e me */.#defin
23690 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 e SQLITE_DROP_VT
236a0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 ABLE 30
236b0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
236c0 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d Module Nam
236d0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 e */.#define
236e0 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e SQLITE_FUNCTION
236f0 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20 31
23700 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 /* NULL
23710 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 Function Na
23720 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 me */.#define
23730 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 SQLITE_SAVEPOINT
23740 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20 32
23750 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 /* Operation
23760 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 Savepoint Na
23770 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 me */.#define S
23780 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 QLITE_COPY
23790 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 0
237a0 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 /* No longer use
237b0 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
237c0 49 54 45 5f 52 45 43 55 52 53 49 56 45 20 20 20 ITE_RECURSIVE
237d0 20 20 20 20 20 20 20 20 20 33 33 20 20 20 2f 2a 33 /*
237e0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
237f0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
23800 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 */../*.** CAPI3
23810 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 REF: Tracing And
23820 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 Profiling Funct
23830 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 ions.** METHOD:
23840 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 sqlite3.**.** Th
23850 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 ese routines reg
23860 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 ister callback f
23870 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 unctions that ca
23880 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a n be used for.**
23890 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f tracing and pro
238a0 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 filing the execu
238b0 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 tion of SQL stat
238c0 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ements..**.** ^T
238d0 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 he callback func
238e0 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 tion registered
238f0 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 by sqlite3_trace
23900 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 () is invoked at
23910 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 .** various time
23920 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 s when an SQL st
23930 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 atement is being
23940 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 run by [sqlite3
23950 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 _step()]..** ^Th
23960 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 e sqlite3_trace(
23970 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e ) callback is in
23980 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 voked with a UTF
23990 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 -8 rendering of
239a0 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 the.** SQL state
239b0 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 ment text as the
239c0 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 statement first
239d0 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e begins executin
239e0 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e g..** ^(Addition
239f0 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 al sqlite3_trace
23a00 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 () callbacks mig
23a10 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 ht occur.** as e
23a20 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 ach triggered su
23a30 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 bprogram is ente
23a40 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 red. The callba
23a50 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 cks for triggers
23a60 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 .** contain a UT
23a70 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 F-8 SQL comment
23a80 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 that identifies
23a90 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a the trigger.)^.*
23aa0 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 *.** The [SQLITE
23ab0 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 _TRACE_SIZE_LIMI
23ac0 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 T] compile-time
23ad0 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 option can be us
23ae0 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 ed to limit.** t
23af0 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f he length of [bo
23b00 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65 und parameter] e
23b10 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 xpansion in the
23b20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65 output of sqlite
23b30 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 3_trace()..**.**
23b40 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 ^The callback f
23b50 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 unction register
23b60 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 ed by sqlite3_pr
23b70 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b ofile() is invok
23b80 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 ed.** as each SQ
23b90 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 L statement fini
23ba0 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 shes. ^The prof
23bb0 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e ile callback con
23bc0 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 tains.** the ori
23bd0 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 ginal statement
23be0 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 text and an esti
23bf0 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f mate of wall-clo
23c00 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f ck time.** of ho
23c10 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 w long that stat
23c20 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 ement took to ru
23c30 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 n. ^The profile
23c40 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d callback.** tim
23c50 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 e is in units of
23c60 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f nanoseconds, ho
23c70 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e wever the curren
23c80 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e t implementation
23c90 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 .** is only capa
23ca0 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f ble of milliseco
23cb0 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f nd resolution so
23cc0 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 the six least s
23cd0 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 ignificant.** di
23ce0 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 gits in the time
23cf0 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 are meaningless
23d00 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f . Future versio
23d10 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 ns of SQLite.**
23d20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 might provide gr
23d30 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e eater resolution
23d40 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 on the profiler
23d50 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a callback. The.
23d60 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 ** sqlite3_profi
23d70 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 le() function is
23d80 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 considered expe
23d90 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a rimental and is.
23da0 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 ** subject to ch
23db0 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 ange in future v
23dc0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
23dd0 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 e..*/.SQLITE_API
23de0 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 void *SQLITE_ST
23df0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74 72 DCALL sqlite3_tr
23e00 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f ace(sqlite3*, vo
23e10 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 id(*xTrace)(void
23e20 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 *,const char*),
23e30 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 void*);.SQLITE_A
23e40 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 PI SQLITE_EXPERI
23e50 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 53 51 4c MENTAL void *SQL
23e60 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
23e70 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 te3_profile(sqli
23e80 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 te3*,. void(*x
23e90 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 Profile)(void*,c
23ea0 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 onst char*,sqlit
23eb0 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 e3_uint64), void
23ec0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
23ed0 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 REF: Query Progr
23ee0 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a ess Callbacks.**
23ef0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
23f00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
23f10 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e te3_progress_han
23f20 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e dler(D,N,X,P) in
23f30 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 terface causes t
23f40 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 he callback.** f
23f50 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 unction X to be
23f60 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 invoked periodic
23f70 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 ally during long
23f80 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 running calls t
23f90 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 o.** [sqlite3_ex
23fa0 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f ec()], [sqlite3_
23fb0 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c step()] and [sql
23fc0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
23fd0 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 ] for.** databas
23fe0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 e connection D.
23ff0 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 An example use
24000 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 for this.** inte
24010 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 rface is to keep
24020 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 a GUI updated d
24030 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 uring a large qu
24040 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ery..**.** ^The
24050 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 parameter P is p
24060 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 assed through as
24070 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 the only parame
24080 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 ter to the .** c
24090 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
240a0 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 X. ^The parame
240b0 74 65 72 20 4e 20 69 73 20 74 68 65 20 61 70 70 ter N is the app
240c0 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20 roximate number
240d0 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 of .** [virtual
240e0 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 machine instruct
240f0 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 ions] that are e
24100 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e valuated between
24110 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 successive.** i
24120 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 nvocations of th
24130 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e e callback X. ^
24140 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 If N is less tha
24150 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70 n one then the p
24160 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c rogress.** handl
24170 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a er is disabled..
24180 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 **.** ^Only a si
24190 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 ngle progress ha
241a0 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 ndler may be def
241b0 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 ined at one time
241c0 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 per.** [databas
241d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 e connection]; s
241e0 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f etting a new pro
241f0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 gress handler ca
24200 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 ncels the.** old
24210 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 one. ^Setting
24220 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e parameter X to N
24230 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 ULL disables the
24240 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 progress handle
24250 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 r..** ^The progr
24260 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 ess handler is a
24270 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 lso disabled by
24280 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 setting N to a v
24290 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 alue less.** tha
242a0 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 n 1..**.** ^If t
242b0 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c he progress call
242c0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e back returns non
242d0 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 -zero, the opera
242e0 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 tion is.** inter
242f0 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 rupted. This fe
24300 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 ature can be use
24310 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 d to implement a
24320 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 .** "Cancel" but
24330 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f ton on a GUI pro
24340 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 gress dialog box
24350 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 ..**.** The prog
24360 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c ress handler cal
24370 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 lback must not d
24380 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 o anything that
24390 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 will modify.** t
243a0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
243b0 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f ection that invo
243c0 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 ked the progress
243d0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 handler..** Not
243e0 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f e that [sqlite3_
243f0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e prepare_v2()] an
24400 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 d [sqlite3_step(
24410 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 )] both modify t
24420 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 heir.** database
24430 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 connections for
24440 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 the meaning of
24450 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 "modify" in this
24460 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a paragraph..**.*
24470 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 /.SQLITE_API voi
24480 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c d SQLITE_STDCALL
24490 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 sqlite3_progres
244a0 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 s_handler(sqlite
244b0 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 3*, int, int(*)(
244c0 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a void*), void*);.
244d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
244e0 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 Opening A New D
244f0 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 atabase Connecti
24500 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f on.** CONSTRUCTO
24510 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a R: sqlite3.**.**
24520 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 ^These routines
24530 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 open an SQLite
24540 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 database file as
24550 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 specified by th
24560 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 e .** filename a
24570 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 rgument. ^The fi
24580 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 lename argument
24590 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 is interpreted a
245a0 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 s UTF-8 for.** s
245b0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e qlite3_open() an
245c0 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 d sqlite3_open_v
245d0 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 2() and as UTF-1
245e0 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 6 in the native
245f0 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f byte.** order fo
24600 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 r sqlite3_open16
24610 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 (). ^(A [databas
24620 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 e connection] ha
24630 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a ndle is usually.
24640 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a ** returned in *
24650 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e ppDb, even if an
24660 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 error occurs.
24670 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 The only excepti
24680 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 on is that.** if
24690 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c SQLite is unabl
246a0 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 e to allocate me
246b0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 mory to hold the
246c0 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 [sqlite3] objec
246d0 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c t,.** a NULL wil
246e0 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 l be written int
246f0 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 o *ppDb instead
24700 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 of a pointer to
24710 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a the [sqlite3].**
24720 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 object.)^ ^(If
24730 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 the database is
24740 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 opened (and/or c
24750 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66 reated) successf
24760 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 ully, then.** [S
24770 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 QLITE_OK] is ret
24780 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 urned. Otherwis
24790 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 e an [error code
247a0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e ] is returned.)^
247b0 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 ^The.** [sqlite
247c0 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 3_errmsg()] or [
247d0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 sqlite3_errmsg16
247e0 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e ()] routines can
247f0 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 be used to obta
24800 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 in.** an English
24810 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 language descri
24820 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 ption of the err
24830 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 or following a f
24840 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a ailure of any.**
24850 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f of the sqlite3_
24860 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e open() routines.
24870 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 .**.** ^The defa
24880 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c ult encoding wil
24890 6c 20 62 65 20 55 54 46 2d 38 20 66 6f 72 20 64 l be UTF-8 for d
248a0 61 74 61 62 61 73 65 73 20 63 72 65 61 74 65 64 atabases created
248b0 20 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 using.** sqlite
248c0 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 3_open() or sqli
248d0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 te3_open_v2().
248e0 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 ^The default enc
248f0 6f 64 69 6e 67 20 66 6f 72 20 64 61 74 61 62 61 oding for databa
24900 73 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 ses.** created u
24910 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 sing sqlite3_ope
24920 6e 31 36 28 29 20 77 69 6c 6c 20 62 65 20 55 54 n16() will be UT
24930 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 F-16 in the nati
24940 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a ve byte order..*
24950 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 *.** Whether or
24960 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 not an error occ
24970 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f urs when it is o
24980 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 pened, resources
24990 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 .** associated w
249a0 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 ith the [databas
249b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 e connection] ha
249c0 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 ndle should be r
249d0 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 eleased by.** pa
249e0 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c ssing it to [sql
249f0 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 ite3_close()] wh
24a00 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 en it is no long
24a10 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a er required..**.
24a20 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f ** The sqlite3_o
24a30 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 pen_v2() interfa
24a40 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 ce works like sq
24a50 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 lite3_open().**
24a60 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 except that it a
24a70 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 ccepts two addit
24a80 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 ional parameters
24a90 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 for additional
24aa0 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 control.** over
24ab0 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 the new database
24ac0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 connection. ^(
24ad0 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 The flags parame
24ae0 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 ter to.** sqlite
24af0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 3_open_v2() can
24b00 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 take one of.** t
24b10 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 he following thr
24b20 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f ee values, optio
24b30 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 nally combined w
24b40 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c ith the .** [SQL
24b50 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 ITE_OPEN_NOMUTEX
24b60 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ], [SQLITE_OPEN_
24b70 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c FULLMUTEX], [SQL
24b80 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 ITE_OPEN_SHAREDC
24b90 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 ACHE],.** [SQLIT
24ba0 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 E_OPEN_PRIVATECA
24bb0 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 CHE], and/or [SQ
24bc0 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 LITE_OPEN_URI] f
24bd0 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 lags:)^.**.** <d
24be0 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c l>.** ^(<dt>[SQL
24bf0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c ITE_OPEN_READONL
24c00 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 Y]</dt>.** <dd>T
24c10 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f he database is o
24c20 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e pened in read-on
24c30 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 ly mode. If the
24c40 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e database does n
24c50 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 ot.** already ex
24c60 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 ist, an error is
24c70 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 returned.</dd>)
24c80 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 ^.**.** ^(<dt>[S
24c90 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 QLITE_OPEN_READW
24ca0 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 RITE]</dt>.** <d
24cb0 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 d>The database i
24cc0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 s opened for rea
24cd0 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 ding and writing
24ce0 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 if possible, or
24cf0 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 reading.** only
24d00 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 if the file is
24d10 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 write protected
24d20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 by the operating
24d30 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 system. In eit
24d40 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 her.** case the
24d50 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c database must al
24d60 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 ready exist, oth
24d70 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 erwise an error
24d80 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 is returned.</dd
24d90 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e >)^.**.** ^(<dt>
24da0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 [SQLITE_OPEN_REA
24db0 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 DWRITE] | [SQLIT
24dc0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f E_OPEN_CREATE]</
24dd0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 dt>.** <dd>The d
24de0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 atabase is opene
24df0 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e d for reading an
24e00 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 d writing, and i
24e10 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 s created if.**
24e20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 it does not alre
24e30 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 ady exist. This
24e40 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 is the behavior
24e50 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 that is always u
24e60 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 sed for.** sqlit
24e70 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 e3_open() and sq
24e80 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c lite3_open16().<
24e90 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a /dd>)^.** </dl>.
24ea0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 **.** If the 3rd
24eb0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
24ec0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
24ed0 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 is not one of th
24ee0 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e e.** combination
24ef0 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 s shown above op
24f00 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 tionally combine
24f10 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 d with other.**
24f20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 [SQLITE_OPEN_REA
24f30 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f DONLY | SQLITE_O
24f40 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 PEN_* bits].** t
24f50 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 hen the behavior
24f60 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a is undefined..*
24f70 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 *.** ^If the [SQ
24f80 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 LITE_OPEN_NOMUTE
24f90 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 X] flag is set,
24fa0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 then the databas
24fb0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 e connection.**
24fc0 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c opens in the mul
24fd0 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 ti-thread [threa
24fe0 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f ding mode] as lo
24ff0 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 ng as the single
25000 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 -thread.** mode
25010 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 has not been set
25020 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 at compile-time
25030 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 or start-time.
25040 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c ^If the.** [SQL
25050 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 ITE_OPEN_FULLMUT
25060 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 EX] flag is set
25070 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 then the databas
25080 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 e connection ope
25090 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 ns.** in the ser
250a0 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 ialized [threadi
250b0 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 ng mode] unless
250c0 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 single-thread wa
250d0 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 s.** previously
250e0 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 selected at comp
250f0 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 ile-time or star
25100 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 t-time..** ^The
25110 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 [SQLITE_OPEN_SHA
25120 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 REDCACHE] flag c
25130 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 auses the databa
25140 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f se connection to
25150 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 be.** eligible
25160 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 to use [shared c
25170 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 ache mode], rega
25180 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 rdless of whethe
25190 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a r or not shared.
251a0 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 ** cache is enab
251b0 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 led using [sqlit
251c0 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 e3_enable_shared
251d0 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 _cache()]. ^The
251e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e .** [SQLITE_OPEN
251f0 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 _PRIVATECACHE] f
25200 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 lag causes the d
25210 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
25220 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 on to not.** par
25230 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 ticipate in [sha
25240 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 red cache mode]
25250 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e even if it is en
25260 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 abled..**.** ^Th
25270 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
25280 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 er to sqlite3_op
25290 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e en_v2() is the n
252a0 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 ame of the.** [s
252b0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
252c0 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 ct that defines
252d0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 the operating sy
252e0 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 stem interface t
252f0 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 hat.** the new d
25300 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
25310 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 on should use.
25320 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 ^If the fourth p
25330 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 arameter is.** a
25340 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 NULL pointer th
25350 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b en the default [
25360 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a sqlite3_vfs] obj
25370 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a ect is used..**.
25380 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e ** ^If the filen
25390 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a ame is ":memory:
253a0 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 ", then a privat
253b0 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d e, temporary in-
253c0 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a memory database.
253d0 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f ** is created fo
253e0 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e r the connection
253f0 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f . ^This in-memo
25400 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c ry database will
25410 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 vanish when.**
25420 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
25430 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 nection is close
25440 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 d. Future versi
25450 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 ons of SQLite mi
25460 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 ght.** make use
25470 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 of additional sp
25480 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 ecial filenames
25490 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 that begin with
254a0 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 the ":" characte
254b0 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f r..** It is reco
254c0 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 mmended that whe
254d0 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c n a database fil
254e0 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 ename actually d
254f0 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a oes begin with.*
25500 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 * a ":" characte
25510 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 r you should pre
25520 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 fix the filename
25530 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 with a pathname
25540 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 such as.** "./"
25550 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 to avoid ambigu
25560 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 ity..**.** ^If t
25570 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 he filename is a
25580 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 n empty string,
25590 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 then a private,
255a0 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d temporary.** on-
255b0 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 disk database wi
255c0 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 ll be created.
255d0 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 ^This private da
255e0 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a tabase will be.*
255f0 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 * automatically
25600 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 deleted as soon
25610 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 as the database
25620 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c connection is cl
25630 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 osed..**.** [[UR
25640 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 I filenames in s
25650 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 qlite3_open()]]
25660 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 <h3>URI Filename
25670 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 s</h3>.**.** ^If
25680 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 [URI filename]
25690 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 interpretation i
256a0 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 s enabled, and t
256b0 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 he filename argu
256c0 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 ment.** begins w
256d0 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 ith "file:", the
256e0 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 n the filename i
256f0 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 s interpreted as
25700 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 a URI. ^URI.**
25710 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 filename interpr
25720 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c etation is enabl
25730 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 ed if the [SQLIT
25740 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 E_OPEN_URI] flag
25750 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 is.** set in th
25760 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e e fourth argumen
25770 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 t to sqlite3_ope
25780 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 n_v2(), or if it
25790 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 has.** been ena
257a0 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 bled globally us
257b0 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ing the [SQLITE_
257c0 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 CONFIG_URI] opti
257d0 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b on with the.** [
257e0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
257f0 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 ] method or by t
25800 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 he [SQLITE_USE_U
25810 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 RI] compile-time
25820 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f option..** As o
25830 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e f SQLite version
25840 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 3.7.7, URI file
25850 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 name interpretat
25860 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 ion is turned of
25870 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c f.** by default,
25880 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 but future rele
25890 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d ases of SQLite m
258a0 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 ight enable URI
258b0 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 filename.** inte
258c0 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 rpretation by de
258d0 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 fault. See "[UR
258e0 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f I filenames]" fo
258f0 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 r additional.**
25900 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a information..**.
25910 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 ** URI filenames
25920 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f are parsed acco
25930 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 rding to RFC 398
25940 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6. ^If the URI c
25950 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 ontains an.** au
25960 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 thority, then it
25970 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 must be either
25980 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 an empty string
25990 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a or the string .*
259a0 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e * "localhost". ^
259b0 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 If the authority
259c0 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 is not an empty
259d0 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 string or "loca
259e0 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 lhost", an .** e
259f0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 rror is returned
25a00 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 to the caller.
25a10 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f ^The fragment co
25a20 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 mponent of a URI
25a30 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 , if .** present
25a40 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a , is ignored..**
25a50 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 .** ^SQLite uses
25a60 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e the path compon
25a70 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 ent of the URI a
25a80 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
25a90 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 e disk file.** w
25aa0 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 hich contains th
25ab0 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 e database. ^If
25ac0 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 the path begins
25ad0 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 with a '/' chara
25ae0 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 cter, .** then i
25af0 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 t is interpreted
25b00 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 as an absolute
25b10 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 path. ^If the pa
25b20 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 th does not begi
25b30 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 n .** with a '/'
25b40 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 (meaning that t
25b50 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 he authority sec
25b60 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 tion is omitted
25b70 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a from the URI).**
25b80 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 then the path i
25b90 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 s interpreted as
25ba0 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 a relative path
25bb0 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f . .** ^(On windo
25bc0 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f ws, the first co
25bd0 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 mponent of an ab
25be0 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 solute path .**
25bf0 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69 is a drive speci
25c00 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 fication (e.g. "
25c10 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b C:").)^.**.** [[
25c20 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70 core URI query p
25c30 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 arameters]].** T
25c40 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 he query compone
25c50 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 nt of a URI may
25c60 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 contain paramete
25c70 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 rs that are inte
25c80 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 rpreted.** eithe
25c90 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 r by SQLite itse
25ca0 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 lf, or by a [VFS
25cb0 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d | custom VFS im
25cc0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a plementation]..*
25cd0 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 69 74 73 * SQLite and its
25ce0 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 built-in [VFSes
25cf0 5d 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a ] interpret the.
25d00 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 ** following que
25d10 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a ry parameters:.*
25d20 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c *.** <ul>.** <
25d30 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 li> <b>vfs</b>:
25d40 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d ^The "vfs" param
25d50 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 eter may be used
25d60 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 to specify the
25d70 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 name of.** a
25d80 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 VFS object that
25d90 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 provides the op
25da0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 erating system i
25db0 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68 nterface that sh
25dc0 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 ould.** be u
25dd0 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 sed to access th
25de0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
25df0 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 on disk. ^If thi
25e00 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 s option is set
25e10 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 to.** an emp
25e20 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 ty string the de
25e30 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 fault VFS object
25e40 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 is used. ^Speci
25e50 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e fying an unknown
25e60 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 .** VFS is a
25e70 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c n error. ^If sql
25e80 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 ite3_open_v2() i
25e90 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 s used and the v
25ea0 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 fs option is.**
25eb0 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 present, the
25ec0 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66 n the VFS specif
25ed0 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f ied by the optio
25ee0 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e n takes preceden
25ef0 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 ce over.** t
25f00 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 he value passed
25f10 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 as the fourth pa
25f20 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
25f30 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a e3_open_v2()..**
25f40 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f .** <li> <b>mo
25f50 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f de</b>: ^(The mo
25f60 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 de parameter may
25f70 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 be set to eithe
25f80 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a r "ro", "rw",.**
25f90 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22 "rwc", or "
25fa0 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 memory". Attempt
25fb0 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f ing to set it to
25fc0 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 any other value
25fd0 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 is.** an er
25fe0 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e ror)^. .** ^
25ff0 49 66 20 22 72 6f 22 20 69 73 20 73 70 65 63 69 If "ro" is speci
26000 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 fied, then the d
26010 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 atabase is opene
26020 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 d for read-only
26030 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 .** access,
26040 6a 75 73 74 20 61 73 20 69 66 20 74 68 65 20 5b just as if the [
26050 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
26060 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62 ONLY] flag had b
26070 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a een set in the .
26080 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61 72 67 ** third arg
26090 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 ument to sqlite3
260a0 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 _open_v2(). ^If
260b0 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 the mode option
260c0 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 is set to .**
260d0 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65 "rw", then the
260e0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 database is ope
260f0 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69 ned for read-wri
26100 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61 te (but not crea
26110 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 te) .** acce
26120 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45 ss, as if SQLITE
26130 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 _OPEN_READWRITE
26140 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f (but not SQLITE_
26150 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64 OPEN_CREATE) had
26160 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65 .** been se
26170 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20 t. ^Value "rwc"
26180 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f is equivalent to
26190 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a setting both .*
261a0 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 * SQLITE_OPE
261b0 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20 N_READWRITE and
261c0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 SQLITE_OPEN_CREA
261d0 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 TE. ^If the mod
261e0 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 e option is.**
261f0 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 set to "memor
26200 79 22 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b y" then a pure [
26210 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 in-memory databa
26220 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72 se] that never r
26230 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 eads.** or w
26240 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 rites from disk
26250 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20 is used. ^It is
26260 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63 an error to spec
26270 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a ify a value for.
26280 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20 ** the mode
26290 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 parameter that i
262a0 73 20 6c 65 73 73 20 72 65 73 74 72 69 63 74 69 s less restricti
262b0 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 70 65 ve than that spe
262c0 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 cified by.**
262d0 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 73 65 the flags passe
262e0 64 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 d in the third p
262f0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
26300 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a te3_open_v2()..*
26310 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 *.** <li> <b>c
26320 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 ache</b>: ^The c
26330 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d ache parameter m
26340 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 ay be set to eit
26350 68 65 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a her "shared" or.
26360 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74 65 22 ** "private"
26370 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f . ^Setting it to
26380 20 22 73 68 61 72 65 64 22 20 69 73 20 65 71 75 "shared" is equ
26390 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 ivalent to setti
263a0 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 ng the.** SQ
263b0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 LITE_OPEN_SHARED
263c0 43 41 43 48 45 20 62 69 74 20 69 6e 20 74 68 65 CACHE bit in the
263d0 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 flags argument
263e0 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 passed to.**
263f0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
26400 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65 (). ^Setting the
26410 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 cache parameter
26420 20 74 6f 20 22 70 72 69 76 61 74 65 22 20 69 73 to "private" is
26430 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c .** equival
26440 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 ent to setting t
26450 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 he SQLITE_OPEN_P
26460 52 49 56 41 54 45 43 41 43 48 45 20 62 69 74 2e RIVATECACHE bit.
26470 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69 .** ^If sqli
26480 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 te3_open_v2() is
26490 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 22 63 used and the "c
264a0 61 63 68 65 22 20 70 61 72 61 6d 65 74 65 72 20 ache" parameter
264b0 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a is present in.**
264c0 20 20 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e a URI filen
264d0 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f ame, its value o
264e0 76 65 72 72 69 64 65 73 20 61 6e 79 20 62 65 68 verrides any beh
264f0 61 76 69 6f 72 20 72 65 71 75 65 73 74 65 64 20 avior requested
26500 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 by setting.**
26510 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 SQLITE_OPEN_PR
26520 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 IVATECACHE or SQ
26530 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 LITE_OPEN_SHARED
26540 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a CACHE flag..**.*
26550 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c * <li> <b>psow<
26560 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 /b>: ^The psow p
26570 61 72 61 6d 65 74 65 72 20 69 6e 64 69 63 61 74 arameter indicat
26580 65 73 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f es whether or no
26590 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f t the.** [po
265a0 77 65 72 73 61 66 65 20 6f 76 65 72 77 72 69 74 wersafe overwrit
265b0 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65 73 e] property does
265c0 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 or does not app
265d0 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 ly to the.**
265e0 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20 6f storage media o
265f0 6e 20 77 68 69 63 68 20 74 68 65 20 64 61 74 61 n which the data
26600 62 61 73 65 20 66 69 6c 65 20 72 65 73 69 64 65 base file reside
26610 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c s..**.** <li> <
26620 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 b>nolock</b>: ^T
26630 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 he nolock parame
26640 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e ter is a boolean
26650 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 query parameter
26660 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 20 69 66 .** which if
26670 20 73 65 74 20 64 69 73 61 62 6c 65 73 20 66 69 set disables fi
26680 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f le locking in ro
26690 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d llback journal m
266a0 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 odes. This.**
266b0 20 20 20 69 73 20 75 73 65 66 75 6c 20 66 6f 72 is useful for
266c0 20 61 63 63 65 73 73 69 6e 67 20 61 20 64 61 74 accessing a dat
266d0 61 62 61 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 abase on a files
266e0 79 73 74 65 6d 20 74 68 61 74 20 64 6f 65 73 20 ystem that does
266f0 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f not.** suppo
26700 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 rt locking. Cau
26710 74 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 65 20 tion: Database
26720 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 corruption might
26730 20 72 65 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a result if two.*
26740 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 * or more pr
26750 6f 63 65 73 73 65 73 20 77 72 69 74 65 20 74 6f ocesses write to
26760 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 the same databa
26770 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f se and any one o
26780 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 f those.** p
26790 72 6f 63 65 73 73 65 73 20 75 73 65 73 20 6e 6f rocesses uses no
267a0 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c lock=1..**.** <
267b0 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 li> <b>immutable
267c0 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 </b>: ^The immut
267d0 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72 20 69 able parameter i
267e0 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 s a boolean quer
267f0 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74 y.** paramet
26800 65 72 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 er that indicate
26810 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 s that the datab
26820 61 73 65 20 66 69 6c 65 20 69 73 20 73 74 6f 72 ase file is stor
26830 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 ed on.** rea
26840 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e d-only media. ^
26850 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 When immutable i
26860 73 20 73 65 74 2c 20 53 51 4c 69 74 65 20 61 73 s set, SQLite as
26870 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a sumes that the.*
26880 2a 20 20 20 20 20 64 61 74 61 62 61 73 65 20 66 * database f
26890 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 ile cannot be ch
268a0 61 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 20 61 anged, even by a
268b0 20 70 72 6f 63 65 73 73 20 77 69 74 68 20 68 69 process with hi
268c0 67 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 gher.** priv
268d0 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 ilege, and so th
268e0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 e database is op
268f0 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 ened read-only a
26900 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a nd all locking.*
26910 2a 20 20 20 20 20 61 6e 64 20 63 68 61 6e 67 65 * and change
26920 20 64 65 74 65 63 74 69 6f 6e 20 69 73 20 64 69 detection is di
26930 73 61 62 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e sabled. Caution
26940 3a 20 53 65 74 74 69 6e 67 20 74 68 65 20 69 6d : Setting the im
26950 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 mutable.** p
26960 72 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 61 74 roperty on a dat
26970 61 62 61 73 65 20 66 69 6c 65 20 74 68 61 74 20 abase file that
26980 64 6f 65 73 20 69 6e 20 66 61 63 74 20 63 68 61 does in fact cha
26990 6e 67 65 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a nge can result.*
269a0 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 * in incorre
269b0 63 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 ct query results
269c0 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f and/or [SQLITE_
269d0 43 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 73 2e CORRUPT] errors.
269e0 0a 2a 2a 20 20 20 20 20 53 65 65 20 61 6c 73 6f .** See also
269f0 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f : [SQLITE_IOCAP_
26a00 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 IMMUTABLE]..**
26a10 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a .** </ul>.*
26a20 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 *.** ^Specifying
26a30 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 an unknown para
26a40 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 meter in the que
26a50 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 ry component of
26a60 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a a URI is not an.
26a70 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 ** error. Futur
26a80 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 e versions of SQ
26a90 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 Lite might under
26aa0 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c stand additional
26ab0 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 query.** parame
26ac0 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 ters. See "[que
26ad0 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 ry parameters wi
26ae0 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 th special meani
26af0 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 ng to SQLite]" f
26b00 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c or.** additional
26b10 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a information..**
26b20 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 .** [[URI filena
26b30 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 me examples]] <h
26b40 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 3>URI filename e
26b50 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a xamples</h3>.**.
26b60 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 ** <table border
26b70 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 ="1" align=cente
26b80 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e r cellpadding=5>
26b90 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 .** <tr><th> URI
26ba0 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 filenames <th>
26bb0 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c Results.** <tr><
26bc0 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 td> file:data.db
26bd0 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 <td> .**
26be0 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 Open the file
26bf0 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 "data.db" in th
26c00 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 e current direct
26c10 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e ory..** <tr><td>
26c20 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 file:/home/fred
26c30 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 /data.db<br>.**
26c40 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f file://
26c50 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e /home/fred/data.
26c60 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 db <br> .**
26c70 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 file://loca
26c80 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f lhost/home/fred/
26c90 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 data.db <br> <td
26ca0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f > .** O
26cb0 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 pen the database
26cc0 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 file "/home/fre
26cd0 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c d/data.db"..** <
26ce0 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 tr><td> file://d
26cf0 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 arkstar/home/fre
26d00 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a d/data.db <td> .
26d10 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 ** An e
26d20 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 rror. "darkstar"
26d30 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e is not a recogn
26d40 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a ized authority..
26d50 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 ** <tr><td style
26d60 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f ="white-space:no
26d70 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 wrap"> .**
26d80 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 file:///C:/D
26d90 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 ocuments%20and%2
26da0 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 0Settings/fred/D
26db0 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a esktop/data.db.*
26dc0 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f * <td> Windo
26dd0 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 ws only: Open th
26de0 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 e file "data.db"
26df0 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 on fred's deskt
26e00 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 op on drive.**
26e10 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 C:. Note
26e20 20 74 68 61 74 20 74 68 65 20 25 32 30 20 65 73 that the %20 es
26e30 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 caping in this e
26e40 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 xample is not st
26e50 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 rictly .**
26e60 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 necessary -
26e70 73 70 61 63 65 20 63 68 61 72 61 63 74 65 72 73 space characters
26e80 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 can be used lit
26e90 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 erally.**
26ea0 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 in URI filena
26eb0 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e mes..** <tr><td>
26ec0 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f file:data.db?mo
26ed0 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 de=ro&cache=priv
26ee0 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 ate <td> .**
26ef0 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 Open file
26f00 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 "data.db" in the
26f10 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f current directo
26f20 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 ry for read-only
26f30 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 access..**
26f40 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 Regardless
26f50 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f of whether or no
26f60 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d t shared-cache m
26f70 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 ode is enabled b
26f80 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 y.** de
26f90 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 fault, use a pri
26fa0 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c vate cache..** <
26fb0 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f tr><td> file:/ho
26fc0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f me/fred/data.db?
26fd0 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 vfs=unix-dotfile
26fe0 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 <td>.**
26ff0 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f Open file "/ho
27000 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 me/fred/data.db"
27010 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69 61 . Use the specia
27020 6c 20 56 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 l VFS "unix-dotf
27030 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 ile".**
27040 20 74 68 61 74 20 75 73 65 73 20 64 6f 74 2d 66 that uses dot-f
27050 69 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 iles in place of
27060 20 70 6f 73 69 78 20 61 64 76 69 73 6f 72 79 20 posix advisory
27070 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e locking..** <tr>
27080 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 <td> file:data.d
27090 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 b?mode=readonly
270a0 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 <td> .**
270b0 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 An error. "rea
270c0 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 donly" is not a
270d0 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 valid option for
270e0 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61 the "mode" para
270f0 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c meter..** </tabl
27100 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 e>.**.** ^URI he
27110 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 xadecimal escape
27120 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48 29 sequences (%HH)
27130 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 77 are supported w
27140 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 61 ithin the path a
27150 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 nd.** query comp
27160 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e onents of a URI.
27170 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 A hexadecimal e
27180 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 63 scape sequence c
27190 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 onsists of a.**
271a0 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 percent sign - "
271b0 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 %" - followed by
271c0 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78 exactly two hex
271d0 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 adecimal digits
271e0 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61 .** specifying a
271f0 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e n octet value. ^
27200 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 20 Before the path
27210 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 or query compone
27220 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 nts of a.** URI
27230 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 filename are int
27240 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 61 erpreted, they a
27250 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 re encoded using
27260 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a UTF-8 and all .
27270 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 ** hexadecimal e
27280 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 scape sequences
27290 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 69 replaced by a si
272a0 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69 ngle byte contai
272b0 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 ning the.** corr
272c0 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e esponding octet.
272d0 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 73 If this process
272e0 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e generates an in
272f0 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f valid UTF-8 enco
27300 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 ding,.** the res
27310 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e ults are undefin
27320 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 ed..**.** <b>Not
27330 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 e to Windows use
27340 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 rs:</b> The enc
27350 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 oding used for t
27360 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 he filename argu
27370 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 ment.** of sqlit
27380 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 e3_open() and sq
27390 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
273a0 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e must be UTF-8, n
273b0 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 ot whatever.** c
273c0 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65 odepage is curre
273d0 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 ntly defined. F
273e0 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e ilenames contain
273f0 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 ing internationa
27400 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 l.** characters
27410 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 must be converte
27420 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 d to UTF-8 prior
27430 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d to passing them
27440 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 into.** sqlite3
27450 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 _open() or sqlit
27460 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a e3_open_v2()..**
27470 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 .** <b>Note to W
27480 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 indows Runtime u
27490 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 sers:</b> The t
274a0 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f emporary directo
274b0 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a ry must be set.*
274c0 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 * prior to calli
274d0 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 ng sqlite3_open(
274e0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 ) or sqlite3_ope
274f0 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69 n_v2(). Otherwi
27500 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 se, various.** f
27510 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65 71 eatures that req
27520 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 uire the use of
27530 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 temporary files
27540 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 may fail..**.**
27550 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 See also: [sqlit
27560 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 e3_temp_director
27570 79 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 y].*/.SQLITE_API
27580 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
27590 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e ALL sqlite3_open
275a0 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a (. const char *
275b0 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 filename, /* D
275c0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 atabase filename
275d0 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 (UTF-8) */. sq
275e0 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 lite3 **ppDb
275f0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 /* OUT: SQ
27600 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a Lite db handle *
27610 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 /.);.SQLITE_API
27620 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 int SQLITE_STDCA
27630 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 LL sqlite3_open1
27640 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 6(. const void
27650 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 *filename, /*
27660 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d Database filenam
27670 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 e (UTF-16) */.
27680 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 sqlite3 **ppDb
27690 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 /* OUT:
276a0 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 SQLite db handle
276b0 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 */.);.SQLITE_AP
276c0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
276d0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 70 65 CALL sqlite3_ope
276e0 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 n_v2(. const ch
276f0 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 ar *filename,
27700 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 /* Database file
27710 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a name (UTF-8) */.
27720 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 sqlite3 **ppDb
27730 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 , /* OUT
27740 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 : SQLite db hand
27750 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 le */. int flag
27760 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 s,
27770 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f /* Flags */. co
27780 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 nst char *zVfs
27790 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 /* Name of
277a0 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 VFS module to u
277b0 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 se */.);../*.**
277c0 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e CAPI3REF: Obtain
277d0 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 Values For URI
277e0 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a Parameters.**.**
277f0 20 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 These are utili
27800 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 ty routines, use
27810 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 ful to VFS imple
27820 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 mentations, that
27830 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 check.** to see
27840 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66 if a database f
27850 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68 ile was a URI th
27860 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 at contained a s
27870 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a pecific query .*
27880 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 * parameter, and
27890 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 if so obtains t
278a0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 he value of that
278b0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 query parameter
278c0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 ..**.** If F is
278d0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
278e0 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 ename pointer pa
278f0 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f ssed into the xO
27900 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 pen() method of
27910 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d .** a VFS implem
27920 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 entation when th
27930 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 e flags paramete
27940 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 r to xOpen() has
27950 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 one or .** more
27960 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f of the [SQLITE_
27970 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 OPEN_URI] or [SQ
27980 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 LITE_OPEN_MAIN_D
27990 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a B] bits set and.
279a0 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 ** P is the name
279b0 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61 of the query pa
279c0 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a rameter, then.**
279d0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 sqlite3_uri_par
279e0 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 ameter(F,P) retu
279f0 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 rns the value of
27a00 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 the P.** parame
27a10 74 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73 ter if it exists
27a20 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 or a NULL point
27a30 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 er if P does not
27a40 20 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a appear as a .**
27a50 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 query parameter
27a60 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 on F. If P is
27a70 61 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 a query paramete
27a80 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f r of F.** has no
27a90 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c explicit value,
27aa0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 then sqlite3_ur
27ab0 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 i_parameter(F,P)
27ac0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f returns.** a po
27ad0 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 inter to an empt
27ae0 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 y string..**.**
27af0 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f The sqlite3_uri_
27b00 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 boolean(F,P,B) r
27b10 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 outine assumes t
27b20 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 hat P is a boole
27b30 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 an.** parameter
27b40 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 and returns true
27b50 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 (1) or false (0
27b60 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 ) according to t
27b70 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 he value.** of P
27b80 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 . The sqlite3_u
27b90 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 ri_boolean(F,P,B
27ba0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ) routine return
27bb0 73 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68 s true (1) if th
27bc0 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 e.** value of qu
27bd0 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 ery parameter P
27be0 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c is one of "yes",
27bf0 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 "true", or "on"
27c00 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 in any.** case
27c10 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 or if the value
27c20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f begins with a no
27c30 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 n-zero number.
27c40 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f The .** sqlite3_
27c50 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c uri_boolean(F,P,
27c60 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 B) routines retu
27c70 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 rns false (0) if
27c80 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a the value of.**
27c90 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 query parameter
27ca0 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f P is one of "no
27cb0 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 ", "false", or "
27cc0 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 off" in any case
27cd0 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 or.** if the va
27ce0 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 lue begins with
27cf0 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 a numeric zero.
27d00 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 If P is not a q
27d10 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 uery.** paramete
27d20 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 r on F or if the
27d30 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 value of P is d
27d40 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e oes not match an
27d50 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 y of the.** abov
27d60 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f e, then sqlite3_
27d70 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c uri_boolean(F,P,
27d80 42 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 B) returns (B!=0
27d90 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c )..**.** The sql
27da0 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 ite3_uri_int64(F
27db0 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f ,P,D) routine co
27dc0 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 nverts the value
27dd0 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 of P into a.**
27de0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 64-bit signed in
27df0 74 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e teger and return
27e00 73 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 s that integer,
27e10 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e or D if P does n
27e20 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 ot.** exist. If
27e30 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 the value of P
27e40 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 is something oth
27e50 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 er than an integ
27e60 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f er, then.** zero
27e70 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
27e80 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e .** If F is a N
27e90 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 ULL pointer, the
27ea0 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 n sqlite3_uri_pa
27eb0 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 rameter(F,P) ret
27ec0 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a urns NULL and.**
27ed0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f sqlite3_uri_boo
27ee0 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 lean(F,P,B) retu
27ef0 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 rns B. If F is
27f00 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 not a NULL point
27f10 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 er and.** is not
27f20 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 a database file
27f30 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 pathname pointe
27f40 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 r that SQLite pa
27f50 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f ssed into the xO
27f60 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f pen.** VFS metho
27f70 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 d, then the beha
27f80 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 vior of this rou
27f90 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 tine is undefine
27fa0 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a d and probably.*
27fb0 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a * undesirable..*
27fc0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e /.SQLITE_API con
27fd0 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f st char *SQLITE_
27fe0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
27ff0 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f uri_parameter(co
28000 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e nst char *zFilen
28010 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 ame, const char
28020 2a 7a 50 61 72 61 6d 29 3b 0a 53 51 4c 49 54 45 *zParam);.SQLITE
28030 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f _API int SQLITE_
28040 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
28050 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 uri_boolean(cons
28060 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 t char *zFile, c
28070 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 onst char *zPara
28080 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 m, int bDefault)
28090 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c ;.SQLITE_API sql
280a0 69 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 ite3_int64 SQLIT
280b0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
280c0 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 3_uri_int64(cons
280d0 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 t char*, const c
280e0 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e har*, sqlite3_in
280f0 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 t64);.../*.** CA
28100 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f PI3REF: Error Co
28110 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 des And Messages
28120 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
28130 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 te3.**.** ^If th
28140 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 71 e most recent sq
28150 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c lite3_* API call
28160 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
28170 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 .** [database c
28180 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61 69 onnection] D fai
28190 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 73 71 led, then the sq
281a0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29 lite3_errcode(D)
281b0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 interface.** re
281c0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 turns the numeri
281d0 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 c [result code]
281e0 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 or [extended res
281f0 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 ult code] for th
28200 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e 0a at.** API call..
28210 2a 2a 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 ** If the most r
28220 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 77 ecent API call w
28230 61 73 20 73 75 63 63 65 73 73 66 75 6c 2c 0a 2a as successful,.*
28240 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 * then the retur
28250 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c n value from sql
28260 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 ite3_errcode() i
28270 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 s undefined..**
28280 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 ^The sqlite3_ext
28290 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a ended_errcode().
282a0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 ** interface is
282b0 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 the same except
282c0 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 that it always r
282d0 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b eturns the .** [
282e0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
282f0 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 code] even when
28300 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
28310 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 codes are.** dis
28320 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 abled..**.** ^Th
28330 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 e sqlite3_errmsg
28340 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 () and sqlite3_e
28350 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e rrmsg16() return
28360 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 English-languag
28370 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 e.** text that d
28380 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 escribes the err
28390 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 or, as either UT
283a0 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 F-8 or UTF-16 re
283b0 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e spectively..** ^
283c0 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 (Memory to hold
283d0 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 the error messag
283e0 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 e string is mana
283f0 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a ged internally..
28400 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 ** The applicati
28410 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 on does not need
28420 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 to worry about
28430 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 freeing the resu
28440 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 lt..** However,
28450 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 the error string
28460 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 might be overwr
28470 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 itten or dealloc
28480 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 ated by.** subse
28490 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f quent calls to o
284a0 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 ther SQLite inte
284b0 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e rface functions.
284c0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 )^.**.** ^The sq
284d0 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69 lite3_errstr() i
284e0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
284f0 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e the English-lan
28500 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 guage text.** th
28510 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 at describes the
28520 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 [result code],
28530 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d as UTF-8..** ^(M
28540 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 emory to hold th
28550 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 e error message
28560 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 string is manage
28570 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 d internally.**
28580 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 and must not be
28590 66 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70 freed by the app
285a0 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a lication)^..**.*
285b0 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 * When the seria
285c0 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 lized [threading
285d0 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 mode] is in use
285e0 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 , it might be th
285f0 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 e.** case that a
28600 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 second error oc
28610 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 curs on a separa
28620 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 te thread in bet
28630 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 ween.** the time
28640 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72 of the first er
28650 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c ror and the call
28660 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 to these interf
28670 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 aces..** When th
28680 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 at happens, the
28690 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c second error wil
286a0 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 l be reported si
286b0 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 nce these.** int
286c0 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 erfaces always r
286d0 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 eport the most r
286e0 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 ecent result. T
286f0 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c o avoid.** this,
28700 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e each thread can
28710 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 obtain exclusiv
28720 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 e use of the [da
28730 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
28740 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b n] D.** by invok
28750 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 ing [sqlite3_mut
28760 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 ex_enter]([sqlit
28770 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 e3_db_mutex](D))
28780 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e before beginnin
28790 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e g.** to use D an
287a0 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 d invoking [sqli
287b0 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d te3_mutex_leave]
287c0 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 ([sqlite3_db_mut
287d0 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a ex](D)) after.**
287e0 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 all calls to th
287f0 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 e interfaces lis
28800 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d ted here are com
28810 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 pleted..**.** If
28820 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 an interface fa
28830 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f ils with SQLITE_
28840 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 MISUSE, that mea
28850 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 ns the interface
28860 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 .** was invoked
28870 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 incorrectly by t
28880 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 he application.
28890 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 In that case, t
288a0 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 he.** error code
288b0 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 and message may
288c0 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 or may not be s
288d0 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 et..*/.SQLITE_AP
288e0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
288f0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 72 72 CALL sqlite3_err
28900 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 code(sqlite3 *db
28910 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
28920 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
28930 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 sqlite3_extende
28940 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 d_errcode(sqlite
28950 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 3 *db);.SQLITE_A
28960 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 PI const char *S
28970 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
28980 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c lite3_errmsg(sql
28990 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 ite3*);.SQLITE_A
289a0 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 PI const void *S
289b0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
289c0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 lite3_errmsg16(s
289d0 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 qlite3*);.SQLITE
289e0 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 _API const char
289f0 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 *SQLITE_STDCALL
28a00 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69 sqlite3_errstr(i
28a10 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 nt);../*.** CAPI
28a20 33 52 45 46 3a 20 50 72 65 70 61 72 65 64 20 53 3REF: Prepared S
28a30 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a tatement Object.
28a40 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 ** KEYWORDS: {pr
28a50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
28a60 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 } {prepared stat
28a70 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e ements}.**.** An
28a80 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 instance of thi
28a90 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 s object represe
28aa0 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c nts a single SQL
28ab0 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 0a statement that.
28ac0 2a 2a 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 ** has been comp
28ad0 69 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61 72 79 iled into binary
28ae0 20 66 6f 72 6d 20 61 6e 64 20 69 73 20 72 65 61 form and is rea
28af0 64 79 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 dy to be evaluat
28b00 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 ed..**.** Think
28b10 6f 66 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 of each SQL stat
28b20 65 6d 65 6e 74 20 61 73 20 61 20 73 65 70 61 72 ement as a separ
28b30 61 74 65 20 63 6f 6d 70 75 74 65 72 20 70 72 6f ate computer pro
28b40 67 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 gram. The.** or
28b50 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 20 iginal SQL text
28b60 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 is source code.
28b70 20 41 20 70 72 65 70 61 72 65 64 20 73 74 61 74 A prepared stat
28b80 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a ement object .**
28b90 20 69 73 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 is the compiled
28ba0 20 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20 20 41 object code. A
28bb0 6c 6c 20 53 51 4c 20 6d 75 73 74 20 62 65 20 63 ll SQL must be c
28bc0 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 0a onverted into a.
28bd0 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 ** prepared stat
28be0 65 6d 65 6e 74 20 62 65 66 6f 72 65 20 69 74 20 ement before it
28bf0 63 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a can be run..**.*
28c00 2a 20 54 68 65 20 6c 69 66 65 2d 63 79 63 6c 65 * The life-cycle
28c10 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 20 73 of a prepared s
28c20 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 tatement object
28c30 75 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b usually goes lik
28c40 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f e this:.**.** <o
28c50 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 l>.** <li> Creat
28c60 65 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 e the prepared s
28c70 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 tatement object
28c80 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 using [sqlite3_p
28c90 72 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a repare_v2()]..**
28ca0 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 <li> Bind value
28cb0 73 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 73 s to [parameters
28cc0 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 ] using the sqli
28cd0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 te3_bind_*().**
28ce0 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e interfaces.
28cf0 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 .** <li> Run the
28d00 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 SQL by calling
28d10 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
28d20 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d one or more tim
28d30 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 es..** <li> Rese
28d40 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 t the prepared s
28d50 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b tatement using [
28d60 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
28d70 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a then go back.**
28d80 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e to step 2.
28d90 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f Do this zero o
28da0 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a r more times..**
28db0 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 <li> Destroy th
28dc0 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b e object using [
28dd0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
28de0 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f ()]..** </ol>.*/
28df0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
28e00 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c sqlite3_stmt sql
28e10 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a ite3_stmt;../*.*
28e20 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d * CAPI3REF: Run-
28e30 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d time Limits.** M
28e40 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a ETHOD: sqlite3.*
28e50 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 *.** ^(This inte
28e60 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 rface allows the
28e70 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 size of various
28e80 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 constructs to b
28e90 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 e limited.** on
28ea0 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 a connection by
28eb0 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 connection basis
28ec0 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 . The first par
28ed0 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a ameter is the.**
28ee0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
28ef0 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d ction] whose lim
28f00 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 it is to be set
28f10 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 or queried. The
28f20 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d .** second param
28f30 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 eter is one of t
28f40 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f he [limit catego
28f50 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e ries] that defin
28f60 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 e a.** class of
28f70 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 constructs to be
28f80 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 size limited.
28f90 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 The third parame
28fa0 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 ter is the.** ne
28fb0 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 w limit for that
28fc0 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a construct.)^.**
28fd0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 .** ^If the new
28fe0 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 limit is a negat
28ff0 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 ive number, the
29000 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 limit is unchang
29010 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 ed..** ^(For eac
29020 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 h limit category
29030 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 SQLITE_LIMIT_<i
29040 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 >NAME</i> there
29050 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 is a .** [limits
29060 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f | hard upper bo
29070 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 und].** set at c
29080 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 ompile-time by a
29090 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 C preprocessor
290a0 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 macro called.**
290b0 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 [limits | SQLITE
290c0 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e _MAX_<i>NAME</i>
290d0 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d ]..** (The "_LIM
290e0 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 IT_" in the name
290f0 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 is changed to "
29100 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 _MAX_".))^.** ^A
29110 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 ttempts to incre
29120 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 ase a limit abov
29130 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 e its hard upper
29140 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 bound are.** si
29150 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 lently truncated
29160 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 to the hard upp
29170 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 er bound..**.**
29180 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 ^Regardless of w
29190 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 hether or not th
291a0 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e e limit was chan
291b0 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 ged, the .** [sq
291c0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 lite3_limit()] i
291d0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
291e0 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 the prior value
291f0 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a of the limit..*
29200 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e * ^Hence, to fin
29210 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 d the current va
29220 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 lue of a limit w
29230 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 ithout changing
29240 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e it,.** simply in
29250 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 voke this interf
29260 61 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69 ace with the thi
29270 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 rd parameter set
29280 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 to -1..**.** Ru
29290 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 n-time limits ar
292a0 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 e intended for u
292b0 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f se in applicatio
292c0 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a ns that manage.*
292d0 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e * both their own
292e0 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 internal databa
292f0 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 se and also data
29300 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63 bases that are c
29310 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 ontrolled.** by
29320 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e untrusted extern
29330 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 al sources. An
29340 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 example applicat
29350 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a ion might be a.*
29360 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 * web browser th
29370 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 at has its own d
29380 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f atabases for sto
29390 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 ring history and
293a0 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 .** separate dat
293b0 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 abases controlle
293c0 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 d by JavaScript
293d0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 applications dow
293e0 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 nloaded.** off t
293f0 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 he Internet. Th
29400 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 e internal datab
29410 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 ases can be give
29420 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 n the.** large,
29430 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 default limits.
29440 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 Databases manag
29450 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 ed by external s
29460 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 ources can.** be
29470 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c given much smal
29480 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 ler limits desig
29490 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 ned to prevent a
294a0 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 denial of servi
294b0 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 ce.** attack. D
294c0 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 evelopers might
294d0 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 also want to use
294e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 the [sqlite3_se
294f0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a t_authorizer()].
29500 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 ** interface to
29510 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 further control
29520 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 untrusted SQL.
29530 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 The size of the
29540 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 database.** crea
29550 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 ted by an untrus
29560 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 ted script can b
29570 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e e contained usin
29580 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 g the.** [max_pa
29590 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d ge_count] [PRAGM
295a0 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 A]..**.** New ru
295b0 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 n-time limit cat
295c0 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 egories may be a
295d0 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 dded in future r
295e0 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 eleases..*/.SQLI
295f0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
29600 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
29610 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 3_limit(sqlite3*
29620 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 , int id, int ne
29630 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 wVal);../*.** CA
29640 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 PI3REF: Run-Time
29650 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 Limit Categorie
29660 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b s.** KEYWORDS: {
29670 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 limit category}
29680 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 {*limit categori
29690 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 es}.**.** These
296a0 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 constants define
296b0 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d various perform
296c0 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 ance limits.** t
296d0 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 hat can be lower
296e0 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 ed at run-time u
296f0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 sing [sqlite3_li
29700 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 mit()]..** The s
29710 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d ynopsis of the m
29720 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 eanings of the v
29730 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 arious limits is
29740 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a shown below..**
29750 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f Additional info
29760 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c rmation is avail
29770 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 able at [limits
29780 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 | Limits in SQLi
29790 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a te]..**.** <dl>.
297a0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ** [[SQLITE_LIMI
297b0 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 T_LENGTH]] ^(<dt
297c0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 >SQLITE_LIMIT_LE
297d0 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 NGTH</dt>.** <dd
297e0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a >The maximum siz
297f0 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 e of any string
29800 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 or BLOB or table
29810 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c row, in bytes.<
29820 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 dd>)^.**.** [[SQ
29830 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c LITE_LIMIT_SQL_L
29840 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 ENGTH]] ^(<dt>SQ
29850 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c LITE_LIMIT_SQL_L
29860 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ENGTH</dt>.** <d
29870 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 d>The maximum le
29880 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 ngth of an SQL s
29890 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 tatement, in byt
298a0 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a es.</dd>)^.**.**
298b0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f [[SQLITE_LIMIT_
298c0 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 COLUMN]] ^(<dt>S
298d0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 QLITE_LIMIT_COLU
298e0 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 MN</dt>.** <dd>T
298f0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 he maximum numbe
29900 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 r of columns in
29910 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 a table definiti
29920 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 on or in the.**
29930 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 result set of a
29940 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 [SELECT] or the
29950 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
29960 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 f columns in an
29970 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 index.** or in a
29980 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 n ORDER BY or GR
29990 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f OUP BY clause.</
299a0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 dd>)^.**.** [[SQ
299b0 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f LITE_LIMIT_EXPR_
299c0 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 DEPTH]] ^(<dt>SQ
299d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f LITE_LIMIT_EXPR_
299e0 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 DEPTH</dt>.** <d
299f0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 d>The maximum de
29a00 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 pth of the parse
29a10 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 tree on any exp
29a20 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a ression.</dd>)^.
29a30 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c **.** [[SQLITE_L
29a40 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 IMIT_COMPOUND_SE
29a50 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c LECT]] ^(<dt>SQL
29a60 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 ITE_LIMIT_COMPOU
29a70 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a ND_SELECT</dt>.*
29a80 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
29a90 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d m number of term
29aa0 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 s in a compound
29ab0 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 SELECT statement
29ac0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b .</dd>)^.**.** [
29ad0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 [SQLITE_LIMIT_VD
29ae0 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 BE_OP]] ^(<dt>SQ
29af0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f LITE_LIMIT_VDBE_
29b00 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 OP</dt>.** <dd>T
29b10 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 he maximum numbe
29b20 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e r of instruction
29b30 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d s in a virtual m
29b40 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a achine program.*
29b50 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d * used to implem
29b60 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 ent an SQL state
29b70 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 ment. This limi
29b80 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 t is not current
29b90 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 ly.** enforced,
29ba0 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 though that migh
29bb0 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f t be added in so
29bc0 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 me future releas
29bd0 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c e of.** SQLite.<
29be0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 /dd>)^.**.** [[S
29bf0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 QLITE_LIMIT_FUNC
29c00 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 TION_ARG]] ^(<dt
29c10 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 >SQLITE_LIMIT_FU
29c20 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a NCTION_ARG</dt>.
29c30 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
29c40 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 um number of arg
29c50 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 uments on a func
29c60 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a tion.</dd>)^.**.
29c70 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ** [[SQLITE_LIMI
29c80 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c T_ATTACHED]] ^(<
29c90 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
29ca0 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a ATTACHED</dt>.**
29cb0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
29cc0 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 number of [ATTA
29cd0 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 CH | attached da
29ce0 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e tabases].)^</dd>
29cf0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
29d00 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 LIMIT_LIKE_PATTE
29d10 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e RN_LENGTH]].** ^
29d20 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
29d30 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c T_LIKE_PATTERN_L
29d40 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ENGTH</dt>.** <d
29d50 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 d>The maximum le
29d60 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 ngth of the patt
29d70 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ern argument to
29d80 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a the [LIKE] or.**
29d90 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 [GLOB] operator
29da0 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 s.</dd>)^.**.**
29db0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 [[SQLITE_LIMIT_V
29dc0 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d ARIABLE_NUMBER]]
29dd0 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 .** ^(<dt>SQLITE
29de0 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f _LIMIT_VARIABLE_
29df0 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c NUMBER</dt>.** <
29e00 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 dd>The maximum i
29e10 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 ndex number of a
29e20 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 ny [parameter] i
29e30 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 n an SQL stateme
29e40 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 nt.)^.**.** [[SQ
29e50 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 LITE_LIMIT_TRIGG
29e60 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 ER_DEPTH]] ^(<dt
29e70 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 >SQLITE_LIMIT_TR
29e80 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e IGGER_DEPTH</dt>
29e90 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
29ea0 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 mum depth of rec
29eb0 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 ursion for trigg
29ec0 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a ers.</dd>)^.**.*
29ed0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 * [[SQLITE_LIMIT
29ee0 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 5d _WORKER_THREADS]
29ef0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c ] ^(<dt>SQLITE_L
29f00 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 IMIT_WORKER_THRE
29f10 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e ADS</dt>.** <dd>
29f20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 The maximum numb
29f30 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79 20 er of auxiliary
29f40 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20 74 worker threads t
29f50 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 hat a single.**
29f60 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
29f70 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c ent] may start.<
29f80 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a /dd>)^.** </dl>.
29f90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
29fa0 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 E_LIMIT_LENGTH
29fb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
29fc0 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 0.#define SQLI
29fd0 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e TE_LIMIT_SQL_LEN
29fe0 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 GTH
29ff0 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 1.#define SQL
2a000 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e ITE_LIMIT_COLUMN
2a010 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2a020 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 2.#define SQ
2a030 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f LITE_LIMIT_EXPR_
2a040 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 DEPTH
2a050 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 3.#define S
2a060 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 QLITE_LIMIT_COMP
2a070 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 OUND_SELECT
2a080 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 4.#define
2a090 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 SQLITE_LIMIT_VDB
2a0a0 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 E_OP
2a0b0 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 5.#define
2a0c0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 SQLITE_LIMIT_FU
2a0d0 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 NCTION_ARG
2a0e0 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 6.#defin
2a0f0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 e SQLITE_LIMIT_A
2a100 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20 TTACHED
2a110 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 7.#defi
2a120 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
2a130 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e LIKE_PATTERN_LEN
2a140 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 GTH 8.#def
2a150 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
2a160 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 _VARIABLE_NUMBER
2a170 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 9.#de
2a180 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
2a190 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 T_TRIGGER_DEPTH
2a1a0 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 10.#d
2a1b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
2a1c0 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 IT_WORKER_THREAD
2a1d0 53 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a S 11..
2a1e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2a1f0 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c Compiling An SQL
2a200 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 Statement.** KE
2a210 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 YWORDS: {SQL sta
2a220 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d tement compiler}
2a230 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
2a240 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 te3.** CONSTRUCT
2a250 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 OR: sqlite3_stmt
2a260 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 .**.** To execut
2a270 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 e an SQL query,
2a280 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 it must first be
2a290 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 compiled into a
2a2a0 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 byte-code.** pr
2a2b0 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 ogram using one
2a2c0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 of these routine
2a2d0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 s..**.** The fir
2a2e0 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 st argument, "db
2a2f0 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 ", is a [databas
2a300 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 e connection] ob
2a310 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a tained from a.**
2a320 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 prior successfu
2a330 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 l call to [sqlit
2a340 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c e3_open()], [sql
2a350 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 ite3_open_v2()]
2a360 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f or.** [sqlite3_o
2a370 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 pen16()]. The d
2a380 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2a390 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 on must not have
2a3a0 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a been closed..**
2a3b0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 .** The second a
2a3c0 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c rgument, "zSql",
2a3d0 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e is the statemen
2a3e0 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 t to be compiled
2a3f0 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 , encoded.** as
2a400 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 either UTF-8 or
2a410 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c UTF-16. The sql
2a420 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 ite3_prepare() a
2a430 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nd sqlite3_prepa
2a440 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 re_v2().** inter
2a450 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c faces use UTF-8,
2a460 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 and sqlite3_pre
2a470 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c pare16() and sql
2a480 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
2a490 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 2().** use UTF-1
2a4a0 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 6..**.** ^If the
2a4b0 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 nByte argument
2a4c0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 is negative, the
2a4d0 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 n zSql is read u
2a4e0 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 p to the.** firs
2a4f0 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f t zero terminato
2a500 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 r. ^If nByte is
2a510 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 69 positive, then i
2a520 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 t is the.** numb
2a530 65 72 20 6f 66 20 62 79 74 65 73 20 72 65 61 64 er of bytes read
2a540 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66 from zSql. ^If
2a550 20 6e 42 79 74 65 20 69 73 20 7a 65 72 6f 2c 20 nByte is zero,
2a560 74 68 65 6e 20 6e 6f 20 70 72 65 70 61 72 65 64 then no prepared
2a570 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 73 .** statement is
2a580 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49 generated..** I
2a590 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f f the caller kno
2a5a0 77 73 20 74 68 61 74 20 74 68 65 20 73 75 70 70 ws that the supp
2a5b0 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e lied string is n
2a5c0 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 ul-terminated, t
2a5d0 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73 20 hen.** there is
2a5e0 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61 a small performa
2a5f0 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f nce advantage to
2a600 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 passing an nByt
2a610 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 e parameter that
2a620 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 .** is the numbe
2a630 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 r of bytes in th
2a640 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c e input string <
2a650 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a i>including</i>.
2a660 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 ** the nul-termi
2a670 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 nator..**.** ^If
2a680 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e pzTail is not N
2a690 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c ULL then *pzTail
2a6a0 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e is made to poin
2a6b0 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 t to the first b
2a6c0 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 yte.** past the
2a6d0 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 end of the first
2a6e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 SQL statement i
2a6f0 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 n zSql. These r
2a700 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 outines only.**
2a710 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 compile the firs
2a720 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a t statement in z
2a730 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 Sql, so *pzTail
2a740 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 is left pointing
2a750 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 to.** what rema
2a760 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a ins uncompiled..
2a770 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 **.** ^*ppStmt i
2a780 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 s left pointing
2a790 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 to a compiled [p
2a7a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2a7b0 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a t] that can be.*
2a7c0 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 * executed using
2a7d0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
2a7e0 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 ]. ^If there is
2a7f0 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 an error, *ppSt
2a800 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 mt is set.** to
2a810 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 NULL. ^If the i
2a820 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 nput text contai
2a830 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 ns no SQL (if th
2a840 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d e input is an em
2a850 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 pty.** string or
2a860 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e a comment) then
2a870 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 *ppStmt is set
2a880 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 to NULL..** The
2a890 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 calling procedur
2a8a0 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 e is responsible
2a8b0 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 for deleting th
2a8c0 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 e compiled.** SQ
2a8d0 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e L statement usin
2a8e0 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c g [sqlite3_final
2a8f0 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 ize()] after it
2a900 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 has finished wit
2a910 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 h it..** ppStmt
2a920 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e may not be NULL.
2a930 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 .**.** ^On succe
2a940 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f ss, the sqlite3_
2a950 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 prepare() family
2a960 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 of routines ret
2a970 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b urn [SQLITE_OK];
2a980 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e .** otherwise an
2a990 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 [error code] is
2a9a0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
2a9b0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 The sqlite3_pre
2a9c0 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 pare_v2() and sq
2a9d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
2a9e0 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 v2() interfaces
2a9f0 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 are.** recommend
2aa00 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 ed for all new p
2aa10 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f rograms. The two
2aa20 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 older interface
2aa30 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a s are retained.*
2aa40 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 * for backwards
2aa50 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 compatibility, b
2aa60 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 ut their use is
2aa70 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 discouraged..**
2aa80 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 ^In the "v2" int
2aa90 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 erfaces, the pre
2aaa0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a pared statement.
2aab0 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72 ** that is retur
2aac0 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 ned (the [sqlite
2aad0 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 3_stmt] object)
2aae0 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 contains a copy
2aaf0 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e of the.** origin
2ab00 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 al SQL text. Thi
2ab10 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 s causes the [sq
2ab20 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e lite3_step()] in
2ab30 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 terface to.** be
2ab40 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 have differently
2ab50 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a in three ways:.
2ab60 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c **.** <ol>.** <l
2ab70 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 i>.** ^If the da
2ab80 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 tabase schema ch
2ab90 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f anges, instead o
2aba0 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c f returning [SQL
2abb0 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 ITE_SCHEMA] as i
2abc0 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 t.** always used
2abd0 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 to do, [sqlite3
2abe0 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 _step()] will au
2abf0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f tomatically reco
2ac00 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a mpile the SQL.**
2ac10 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 statement and t
2ac20 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 ry to run it aga
2ac30 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b in. As many as [
2ac40 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d SQLITE_MAX_SCHEM
2ac50 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 A_RETRY].** retr
2ac60 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 ies will occur b
2ac70 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74 efore sqlite3_st
2ac80 65 70 28 29 20 67 69 76 65 73 20 75 70 20 61 6e ep() gives up an
2ac90 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72 d returns an err
2aca0 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a or..** </li>.**.
2acb0 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e ** <li>.** ^When
2acc0 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 an error occurs
2acd0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 , [sqlite3_step(
2ace0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f )] will return o
2acf0 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c ne of the detail
2ad00 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 ed.** [error cod
2ad10 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 es] or [extended
2ad20 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 error codes].
2ad30 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 ^The legacy beha
2ad40 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a vior was that.**
2ad50 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
2ad60 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 ] would only ret
2ad70 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 urn a generic [S
2ad80 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 QLITE_ERROR] res
2ad90 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 ult code.** and
2ada0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
2adb0 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 would have to ma
2adc0 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c ke a second call
2add0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 to [sqlite3_res
2ade0 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 et()].** in orde
2adf0 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e r to find the un
2ae00 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f derlying cause o
2ae10 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 f the problem. W
2ae20 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65 ith the "v2" pre
2ae30 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 pare.** interfac
2ae40 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 es, the underlyi
2ae50 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 ng reason for th
2ae60 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 e error is retur
2ae70 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e ned immediately.
2ae80 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 .** </li>.**.**
2ae90 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 <li>.** ^If the
2aea0 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 specific value b
2aeb0 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 ound to [paramet
2aec0 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 er | host parame
2aed0 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 ter] in the .**
2aee0 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 WHERE clause mig
2aef0 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 ht influence the
2af00 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 choice of query
2af10 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 plan for a stat
2af20 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 ement,.** then t
2af30 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c he statement wil
2af40 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c l be automatical
2af50 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 ly recompiled, a
2af60 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62 s if there had b
2af70 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 een .** a schema
2af80 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 change, on the
2af90 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f first [sqlite3_
2afa0 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c step()] call fol
2afb0 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 lowing any chang
2afc0 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c e.** to the [sql
2afd0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c ite3_bind_text |
2afe0 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 bindings] of th
2aff0 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 at [parameter].
2b000 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 .** ^The specifi
2b010 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 c value of WHERE
2b020 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 -clause [paramet
2b030 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 er] might influe
2b040 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 nce the .** choi
2b050 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e ce of query plan
2b060 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 if the paramete
2b070 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 r is the left-ha
2b080 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 nd side of a [LI
2b090 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d KE].** or [GLOB]
2b0a0 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 operator or if
2b0b0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 the parameter is
2b0c0 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 compared to an
2b0d0 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a indexed column.*
2b0e0 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 * and the [SQLIT
2b0f0 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 E_ENABLE_STAT3]
2b100 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
2b110 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a ion is enabled..
2b120 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c ** </li>.** </ol
2b130 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 >.*/.SQLITE_API
2b140 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 int SQLITE_STDCA
2b150 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 LL sqlite3_prepa
2b160 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 re(. sqlite3 *d
2b170 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a b, /*
2b180 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 Database handle
2b190 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
2b1a0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a *zSql, /*
2b1b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 SQL statement,
2b1c0 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f UTF-8 encoded */
2b1d0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 . int nByte,
2b1e0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 /* Ma
2b1f0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 ximum length of
2b200 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a zSql in bytes. *
2b210 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 /. sqlite3_stmt
2b220 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f **ppStmt, /* O
2b230 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 UT: Statement ha
2b240 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
2b250 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 char **pzTail
2b260 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 /* OUT: Pointe
2b270 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 r to unused port
2b280 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 ion of zSql */.)
2b290 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
2b2a0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
2b2b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
2b2c0 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 v2(. sqlite3 *d
2b2d0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a b, /*
2b2e0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 Database handle
2b2f0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
2b300 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a *zSql, /*
2b310 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 SQL statement,
2b320 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f UTF-8 encoded */
2b330 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 . int nByte,
2b340 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 /* Ma
2b350 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 ximum length of
2b360 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a zSql in bytes. *
2b370 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 /. sqlite3_stmt
2b380 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f **ppStmt, /* O
2b390 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 UT: Statement ha
2b3a0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
2b3b0 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 char **pzTail
2b3c0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 /* OUT: Pointe
2b3d0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 r to unused port
2b3e0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 ion of zSql */.)
2b3f0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
2b400 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
2b410 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
2b420 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 6(. sqlite3 *db
2b430 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 , /*
2b440 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 Database handle
2b450 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 */. const void
2b460 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 *zSql, /*
2b470 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 SQL statement, U
2b480 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f TF-16 encoded */
2b490 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 . int nByte,
2b4a0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 /* Ma
2b4b0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 ximum length of
2b4c0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a zSql in bytes. *
2b4d0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 /. sqlite3_stmt
2b4e0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f **ppStmt, /* O
2b4f0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 UT: Statement ha
2b500 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
2b510 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 void **pzTail
2b520 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 /* OUT: Pointe
2b530 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 r to unused port
2b540 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 ion of zSql */.)
2b550 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
2b560 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
2b570 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
2b580 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 6_v2(. sqlite3
2b590 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 *db,
2b5a0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 /* Database hand
2b5b0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f le */. const vo
2b5c0 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 id *zSql,
2b5d0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 /* SQL statement
2b5e0 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 , UTF-16 encoded
2b5f0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c */. int nByte,
2b600 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
2b610 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 Maximum length
2b620 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 of zSql in bytes
2b630 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 . */. sqlite3_s
2b640 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f tmt **ppStmt, /
2b650 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 * OUT: Statement
2b660 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
2b670 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c st void **pzTail
2b680 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 /* OUT: Poi
2b690 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 nter to unused p
2b6a0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a ortion of zSql *
2b6b0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.);../*.** CAPI
2b6c0 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 3REF: Retrieving
2b6d0 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a Statement SQL.*
2b6e0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
2b6f0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 3_stmt.**.** ^Th
2b700 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e is interface can
2b710 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 be used to retr
2b720 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 ieve a saved cop
2b730 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 y of the origina
2b740 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 l.** SQL text us
2b750 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b ed to create a [
2b760 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2b770 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 nt] if that stat
2b780 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d ement was.** com
2b790 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 piled using eith
2b7a0 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 er [sqlite3_prep
2b7b0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 are_v2()] or [sq
2b7c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
2b7d0 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 v2()]..*/.SQLITE
2b7e0 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 _API const char
2b7f0 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 *SQLITE_STDCALL
2b800 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 sqlite3_sql(sqli
2b810 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 te3_stmt *pStmt)
2b820 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2b830 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 F: Determine If
2b840 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 An SQL Statement
2b850 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61 Writes The Data
2b860 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 base.** METHOD:
2b870 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a sqlite3_stmt.**.
2b880 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
2b890 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 stmt_readonly(X)
2b8a0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
2b8b0 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 ns true (non-zer
2b8c0 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c o) if.** and onl
2b8d0 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 y if the [prepar
2b8e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 ed statement] X
2b8f0 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 makes no direct
2b900 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 changes to.** th
2b910 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 e content of the
2b920 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a database file..
2b930 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 **.** Note that
2b940 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 [application-def
2b950 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f ined SQL functio
2b960 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 ns] or.** [virtu
2b970 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 al tables] might
2b980 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 change the data
2b990 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 base indirectly
2b9a0 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74 as a side effect
2b9b0 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 . .** ^(For exa
2b9c0 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c mple, if an appl
2b9d0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 ication defines
2b9e0 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c a function "eval
2b9f0 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c ()" that .** cal
2ba00 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 ls [sqlite3_exec
2ba10 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f ()], then the fo
2ba20 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 llowing SQL stat
2ba30 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 ement would.** c
2ba40 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 hange the databa
2ba50 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 se file through
2ba60 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a side-effects:.**
2ba70 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
2ba80 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 <pre>.** SELE
2ba90 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 CT eval('DELETE
2baa0 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 FROM t1') FROM t
2bab0 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 2;.** </pre></bl
2bac0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 ockquote>.**.**
2bad0 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20 But because the
2bae0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 [SELECT] stateme
2baf0 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e nt does not chan
2bb00 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ge the database
2bb10 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 file.** directly
2bb20 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 , sqlite3_stmt_r
2bb30 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 eadonly() would
2bb40 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 still return tru
2bb50 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e e.)^.**.** ^Tran
2bb60 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 saction control
2bb70 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 statements such
2bb80 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d as [BEGIN], [COM
2bb90 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d MIT], [ROLLBACK]
2bba0 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d ,.** [SAVEPOINT]
2bbb0 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 , and [RELEASE]
2bbc0 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 cause sqlite3_st
2bbd0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f mt_readonly() to
2bbe0 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a return true,.**
2bbf0 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 since the state
2bc00 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 ments themselves
2bc10 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 do not actually
2bc20 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 modify the data
2bc30 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 base but.** rath
2bc40 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 er they control
2bc50 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 the timing of wh
2bc60 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 en other stateme
2bc70 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a nts modify the .
2bc80 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 ** database. ^T
2bc90 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 he [ATTACH] and
2bca0 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 [DETACH] stateme
2bcb0 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a nts also cause.*
2bcc0 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 * sqlite3_stmt_r
2bcd0 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 eadonly() to ret
2bce0 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 urn true since,
2bcf0 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 while those stat
2bd00 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 ements.** change
2bd10 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 the configurati
2bd20 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 on of a database
2bd30 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 connection, the
2bd40 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a y do not make .*
2bd50 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 * changes to the
2bd60 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 content of the
2bd70 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f database files o
2bd80 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 n disk..*/.SQLIT
2bd90 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
2bda0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
2bdb0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 _stmt_readonly(s
2bdc0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
2bdd0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 mt);../*.** CAPI
2bde0 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 3REF: Determine
2bdf0 49 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74 If A Prepared St
2be00 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e atement Has Been
2be10 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 Reset.** METHOD
2be20 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a : sqlite3_stmt.*
2be30 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
2be40 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69 3_stmt_busy(S) i
2be50 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
2be60 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 true (non-zero)
2be70 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 if the.** [prep
2be80 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
2be90 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 70 70 S has been stepp
2bea0 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 ed at least once
2beb0 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 using .** [sqli
2bec0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74 te3_step(S)] but
2bed0 20 68 61 73 20 6e 65 69 74 68 65 72 20 72 75 6e has neither run
2bee0 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 28 to completion (
2bef0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c returned.** [SQL
2bf00 49 54 45 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b ITE_DONE] from [
2bf10 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d sqlite3_step(S)]
2bf20 29 20 6e 6f 72 0a 2a 2a 20 62 65 65 6e 20 72 65 ) nor.** been re
2bf30 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 set using [sqlit
2bf40 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e e3_reset(S)]. ^
2bf50 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 The sqlite3_stmt
2bf60 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 _busy(S).** inte
2bf70 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 66 61 rface returns fa
2bf80 6c 73 65 20 69 66 20 53 20 69 73 20 61 20 4e 55 lse if S is a NU
2bf90 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 LL pointer. If
2bfa0 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e S is not a .** N
2bfb0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 ULL pointer and
2bfc0 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 is not a pointer
2bfd0 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65 to a valid [pre
2bfe0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2bff0 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e .** object, then
2c000 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 the behavior is
2c010 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 undefined and p
2c020 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 robably undesira
2c030 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 ble..**.** This
2c040 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 interface can be
2c050 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 used in combina
2c060 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 tion [sqlite3_ne
2c070 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f xt_stmt()].** to
2c080 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70 locate all prep
2c090 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 ared statements
2c0a0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
2c0b0 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 a database .** c
2c0c0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61 onnection that a
2c0d0 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 re in need of be
2c0e0 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69 73 ing reset. This
2c0f0 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a can be used,.**
2c100 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e for example, in
2c110 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 diagnostic rout
2c120 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20 66 ines to search f
2c130 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 or prepared .**
2c140 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 statements that
2c150 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 are holding a tr
2c160 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a ansaction open..
2c170 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
2c180 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
2c190 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 sqlite3_stmt_bu
2c1a0 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a sy(sqlite3_stmt*
2c1b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2c1c0 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 EF: Dynamically
2c1d0 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 Typed Value Obje
2c1e0 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 ct.** KEYWORDS:
2c1f0 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 {protected sqlit
2c200 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f e3_value} {unpro
2c210 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
2c220 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 alue}.**.** SQLi
2c230 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 te uses the sqli
2c240 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
2c250 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c to represent al
2c260 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 l values.** that
2c270 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 can be stored i
2c280 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 n a database tab
2c290 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 le. SQLite uses
2c2a0 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a dynamic typing.*
2c2b0 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 * for the values
2c2c0 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 it stores. ^Va
2c2d0 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 lues stored in s
2c2e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
2c2f0 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 ects.** can be i
2c300 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e ntegers, floatin
2c310 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 g point values,
2c320 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 strings, BLOBs,
2c330 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 or NULL..**.** A
2c340 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 n sqlite3_value
2c350 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 object may be ei
2c360 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 ther "protected"
2c370 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 or "unprotected
2c380 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 "..** Some inter
2c390 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 faces require a
2c3a0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
2c3b0 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 3_value. Other
2c3c0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 interfaces.** wi
2c3d0 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 ll accept either
2c3e0 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 a protected or
2c3f0 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 an unprotected s
2c400 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a qlite3_value..**
2c410 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 Every interface
2c420 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 that accepts sq
2c430 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 lite3_value argu
2c440 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a ments specifies.
2c450 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f ** whether or no
2c460 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 t it requires a
2c470 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
2c480 33 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 3_value. The.**
2c490 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
2c4a0 64 75 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 dup()] interface
2c4b0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
2c4c0 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65 77 20 construct a new
2c4d0 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64 20 73 71 .** protected sq
2c4e0 6c 69 74 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d lite3_value from
2c4f0 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 an unprotected
2c500 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a sqlite3_value..*
2c510 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 *.** The terms "
2c520 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 protected" and "
2c530 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 unprotected" ref
2c540 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 er to whether or
2c550 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 not.** a mutex
2c560 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 is held. An int
2c570 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 ernal mutex is h
2c580 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 eld for a protec
2c590 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 ted.** sqlite3_v
2c5a0 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 alue object but
2c5b0 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 no mutex is held
2c5c0 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 for an unprotec
2c5d0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 ted.** sqlite3_v
2c5e0 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 alue object. If
2c5f0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
2c600 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 led to be single
2c610 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 -threaded.** (wi
2c620 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 th [SQLITE_THREA
2c630 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 DSAFE=0] and wit
2c640 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 h [sqlite3_threa
2c650 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 dsafe()] returni
2c660 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 ng 0).** or if S
2c670 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 QLite is run in
2c680 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d one of reduced m
2c690 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b utex modes .** [
2c6a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 SQLITE_CONFIG_SI
2c6b0 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b NGLETHREAD] or [
2c6c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
2c6d0 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 LTITHREAD].** th
2c6e0 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 en there is no d
2c6f0 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 istinction betwe
2c700 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 en protected and
2c710 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 unprotected.**
2c720 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
2c730 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 jects and they c
2c740 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 an be used inter
2c750 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 changeably. How
2c760 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 ever,.** for max
2c770 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 imum code portab
2c780 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f ility it is reco
2c790 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 mmended that app
2c7a0 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 lications.** sti
2c7b0 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 ll make the dist
2c7c0 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 inction between
2c7d0 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e protected and un
2c7e0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c protected.** sql
2c7f0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
2c800 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 ts even when not
2c810 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 strictly requir
2c820 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ed..**.** ^The s
2c830 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
2c840 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 ects that are pa
2c850 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 ssed as paramete
2c860 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 rs into the.** i
2c870 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
2c880 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 [application-de
2c890 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 fined SQL functi
2c8a0 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 ons] are protect
2c8b0 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 ed..** ^The sqli
2c8c0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
2c8d0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 returned by.**
2c8e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
2c8f0 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 value()] is unpr
2c900 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 otected..** Unpr
2c910 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
2c920 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 value objects ma
2c930 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 y only be used w
2c940 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ith.** [sqlite3_
2c950 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 result_value()]
2c960 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e and [sqlite3_bin
2c970 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 d_value()]..** T
2c980 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 he [sqlite3_valu
2c990 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 e_blob | sqlite3
2c9a0 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 _value_type()] f
2c9b0 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 amily of.** inte
2c9c0 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70 rfaces require p
2c9d0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
2c9e0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a _value objects..
2c9f0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
2ca00 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 t Mem sqlite3_va
2ca10 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 lue;../*.** CAPI
2ca20 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 3REF: SQL Functi
2ca30 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 on Context Objec
2ca40 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 t.**.** The cont
2ca50 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 ext in which an
2ca60 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 SQL function exe
2ca70 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 cutes is stored
2ca80 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 in an.** sqlite3
2ca90 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e _context object.
2caa0 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 ^A pointer to
2cab0 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 an sqlite3_conte
2cac0 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 xt object.** is
2cad0 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 always first par
2cae0 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 ameter to [appli
2caf0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 cation-defined S
2cb00 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a QL functions]..*
2cb10 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f * The applicatio
2cb20 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 n-defined SQL fu
2cb30 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 nction implement
2cb40 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 ation will pass
2cb50 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 this.** pointer
2cb60 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c through into cal
2cb70 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 ls to [sqlite3_r
2cb80 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 esult_int | sqli
2cb90 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a te3_result()],.*
2cba0 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 * [sqlite3_aggre
2cbb0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c gate_context()],
2cbc0 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 [sqlite3_user_d
2cbd0 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 ata()],.** [sqli
2cbe0 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 te3_context_db_h
2cbf0 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 andle()], [sqlit
2cc00 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 e3_get_auxdata()
2cc10 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 ],.** and/or [sq
2cc20 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 lite3_set_auxdat
2cc30 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 a()]..*/.typedef
2cc40 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
2cc50 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f context sqlite3_
2cc60 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 context;../*.**
2cc70 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e CAPI3REF: Bindin
2cc80 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 g Values To Prep
2cc90 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a ared Statements.
2cca0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f ** KEYWORDS: {ho
2ccb0 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 st parameter} {h
2ccc0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 ost parameters}
2ccd0 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 {host parameter
2cce0 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 name}.** KEYWORD
2ccf0 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 S: {SQL paramete
2cd00 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 r} {SQL paramete
2cd10 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 rs} {parameter b
2cd20 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f inding}.** METHO
2cd30 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a D: sqlite3_stmt.
2cd40 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 **.** ^(In the S
2cd50 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 QL statement tex
2cd60 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 t input to [sqli
2cd70 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
2cd80 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e ] and its varian
2cd90 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 ts,.** literals
2cda0 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 may be replaced
2cdb0 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d by a [parameter]
2cdc0 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e that matches on
2cdd0 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a e of following.*
2cde0 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a * templates:.**.
2cdf0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ul>.** <li>
2ce00 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e ?.** <li> ?NNN
2ce10 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a .** <li> :VVV.*
2ce20 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 * <li> @VVV.**
2ce30 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f <li> $VVV.** </
2ce40 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 ul>.**.** In the
2ce50 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 templates above
2ce60 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 , NNN represents
2ce70 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 an integer lite
2ce80 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 ral,.** and VVV
2ce90 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c represents an al
2cea0 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 phanumeric ident
2ceb0 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 ifier.)^ ^The v
2cec0 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a alues of these.*
2ced0 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c * parameters (al
2cee0 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 so called "host
2cef0 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 parameter names"
2cf00 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 or "SQL paramet
2cf10 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 ers").** can be
2cf20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 set using the sq
2cf30 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 lite3_bind_*() r
2cf40 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 outines defined
2cf50 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 here..**.** ^The
2cf60 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
2cf70 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 to the sqlite3_b
2cf80 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 ind_*() routines
2cf90 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 is always.** a
2cfa0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b pointer to the [
2cfb0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 sqlite3_stmt] ob
2cfc0 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 ject returned fr
2cfd0 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 om.** [sqlite3_p
2cfe0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 repare_v2()] or
2cff0 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a its variants..**
2d000 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 .** ^The second
2d010 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 argument is the
2d020 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c index of the SQL
2d030 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 parameter to be
2d040 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 set..** ^The le
2d050 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d ftmost SQL param
2d060 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 eter has an inde
2d070 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 x of 1. ^When t
2d080 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a he same named.**
2d090 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 SQL parameter i
2d0a0 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e s used more than
2d0b0 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e once, second an
2d0c0 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 d subsequent.**
2d0d0 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 occurrences have
2d0e0 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 the same index
2d0f0 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 as the first occ
2d100 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 urrence..** ^The
2d110 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 index for named
2d120 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 parameters can
2d130 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 be looked up usi
2d140 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 ng the.** [sqlit
2d150 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
2d160 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 r_index()] API i
2d170 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 f desired. ^The
2d180 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f index.** for "?
2d190 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 NNN" parameters
2d1a0 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 is the value of
2d1b0 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e NNN..** ^The NNN
2d1c0 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 value must be b
2d1d0 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 etween 1 and the
2d1e0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 [sqlite3_limit(
2d1f0 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 )].** parameter
2d200 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 [SQLITE_LIMIT_VA
2d210 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 RIABLE_NUMBER] (
2d220 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 default value: 9
2d230 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 99)..**.** ^The
2d240 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 third argument i
2d250 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 s the value to b
2d260 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d ind to the param
2d270 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 eter..** ^If the
2d280 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
2d290 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 to sqlite3_bind
2d2a0 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 _text() or sqlit
2d2b0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 e3_bind_text16()
2d2c0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 .** or sqlite3_b
2d2d0 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 ind_blob() is a
2d2e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 NULL pointer the
2d2f0 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 n the fourth par
2d300 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e ameter.** is ign
2d310 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64 ored and the end
2d320 20 72 65 73 75 6c 74 20 69 73 20 74 68 65 20 73 result is the s
2d330 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62 ame as sqlite3_b
2d340 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a ind_null()..**.*
2d350 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 * ^(In those rou
2d360 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 tines that have
2d370 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e a fourth argumen
2d380 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 t, its value is
2d390 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 the.** number of
2d3a0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 bytes in the pa
2d3b0 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 rameter. To be
2d3c0 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 clear: the value
2d3d0 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 is the.** numbe
2d3e0 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 r of <u>bytes</u
2d3f0 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 > in the value,
2d400 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f not the number o
2d410 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a f characters.)^.
2d420 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 ** ^If the fourt
2d430 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 h parameter to s
2d440 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
2d450 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 () or sqlite3_bi
2d460 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 nd_text16().** i
2d470 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e s negative, then
2d480 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 the length of t
2d490 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 he string is.**
2d4a0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
2d4b0 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 tes up to the fi
2d4c0 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 rst zero termina
2d4d0 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 tor..** If the f
2d4e0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
2d4f0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f to sqlite3_bind_
2d500 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 blob() is negati
2d510 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 ve, then.** the
2d520 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 behavior is unde
2d530 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e fined..** If a n
2d540 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 on-negative four
2d550 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 th parameter is
2d560 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 provided to sqli
2d570 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a te3_bind_text().
2d580 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 ** or sqlite3_bi
2d590 6e 64 5f 74 65 78 74 31 36 28 29 20 6f 72 20 73 nd_text16() or s
2d5a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
2d5b0 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61 64() then.** tha
2d5c0 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 t parameter must
2d5d0 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 be the byte off
2d5e0 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 set.** where the
2d5f0 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 NUL terminator
2d600 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 would occur assu
2d610 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 ming the string
2d620 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d were NUL.** term
2d630 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 inated. If any
2d640 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f NUL characters o
2d650 63 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 ccur at byte off
2d660 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a sets less than .
2d670 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 ** the value of
2d680 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d the fourth param
2d690 65 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 eter then the re
2d6a0 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 sulting string v
2d6b0 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e alue will.** con
2d6c0 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 tain embedded NU
2d6d0 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 Ls. The result
2d6e0 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 of expressions i
2d6f0 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 nvolving strings
2d700 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 .** with embedde
2d710 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 d NULs is undefi
2d720 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ned..**.** ^The
2d730 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 fifth argument t
2d740 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e 64 20 73 o the BLOB and s
2d750 74 72 69 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e tring binding in
2d760 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 61 terfaces.** is a
2d770 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 destructor used
2d780 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 to dispose of t
2d790 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 he BLOB or.** st
2d7a0 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 ring after SQLit
2d7b0 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 e has finished w
2d7c0 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 ith it. ^The de
2d7d0 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c structor is call
2d7e0 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 ed.** to dispose
2d7f0 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 of the BLOB or
2d800 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 string even if t
2d810 68 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20 he call to bind
2d820 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 API fails..** ^I
2d830 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 f the fifth argu
2d840 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 ment is.** the s
2d850 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 pecial value [SQ
2d860 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 LITE_STATIC], th
2d870 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 en SQLite assume
2d880 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e s that the.** in
2d890 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 formation is in
2d8a0 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 static, unmanage
2d8b0 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 d space and does
2d8c0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 not need to be
2d8d0 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 freed..** ^If th
2d8e0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 e fifth argument
2d8f0 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b has the value [
2d900 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 SQLITE_TRANSIENT
2d910 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 ], then.** SQLit
2d920 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 e makes its own
2d930 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 private copy of
2d940 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 the data immedia
2d950 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 tely, before.**
2d960 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 the sqlite3_bind
2d970 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 _*() routine ret
2d980 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 urns..**.** ^The
2d990 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 sixth argument
2d9a0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f to sqlite3_bind_
2d9b0 74 65 78 74 36 34 28 29 20 6d 75 73 74 20 62 65 text64() must be
2d9c0 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 one of.** [SQLI
2d9d0 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 TE_UTF8], [SQLIT
2d9e0 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 E_UTF16], [SQLIT
2d9f0 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b E_UTF16BE], or [
2da00 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a SQLITE_UTF16LE].
2da10 2a 2a 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 ** to specify th
2da20 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 e encoding of th
2da30 65 20 74 65 78 74 20 69 6e 20 74 68 65 20 74 68 e text in the th
2da40 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 ird parameter.
2da50 49 66 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 20 If.** the sixth
2da60 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 argument to sqli
2da70 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 te3_bind_text64(
2da80 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 ) is not one of
2da90 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 the.** allowed v
2daa0 61 6c 75 65 73 20 73 68 6f 77 6e 20 61 62 6f 76 alues shown abov
2dab0 65 2c 20 6f 72 20 69 66 20 74 68 65 20 74 65 78 e, or if the tex
2dac0 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 t encoding is di
2dad0 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 fferent.** from
2dae0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 the encoding spe
2daf0 63 69 66 69 65 64 20 62 79 20 74 68 65 20 73 69 cified by the si
2db00 78 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 74 xth parameter, t
2db10 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 hen the behavior
2db20 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 .** is undefined
2db30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
2db40 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c ite3_bind_zerobl
2db50 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e ob() routine bin
2db60 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e ds a BLOB of len
2db70 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 gth N that.** is
2db80 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 filled with zer
2db90 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f oes. ^A zeroblo
2dba0 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 b uses a fixed a
2dbb0 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a mount of memory.
2dbc0 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 ** (just an inte
2dbd0 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 ger to hold its
2dbe0 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 size) while it i
2dbf0 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 s being processe
2dc00 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 d..** Zeroblobs
2dc10 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 are intended to
2dc20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f serve as placeho
2dc30 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 lders for BLOBs
2dc40 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 whose.** content
2dc50 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 is later writte
2dc60 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 n using.** [sqli
2dc70 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 te3_blob_open |
2dc80 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 incremental BLOB
2dc90 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a I/O] routines..
2dca0 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 ** ^A negative v
2dcb0 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 alue for the zer
2dcc0 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e oblob results in
2dcd0 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 a zero-length B
2dce0 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 LOB..**.** ^If a
2dcf0 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 ny of the sqlite
2dd00 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 3_bind_*() routi
2dd10 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 nes are called w
2dd20 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 ith a NULL point
2dd30 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 er.** for the [p
2dd40 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2dd50 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 t] or with a pre
2dd60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 pared statement
2dd70 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 for which.** [sq
2dd80 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 lite3_step()] ha
2dd90 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f s been called mo
2dda0 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e re recently than
2ddb0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
2ddc0 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 )],.** then the
2ddd0 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e call will return
2dde0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d [SQLITE_MISUSE]
2ddf0 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 . If any sqlite
2de00 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 3_bind_().** rou
2de10 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 tine is passed a
2de20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2de30 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 ment] that has b
2de40 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 een finalized, t
2de50 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 he.** result is
2de60 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 undefined and pr
2de70 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a obably harmful..
2de80 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 **.** ^Bindings
2de90 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 are not cleared
2dea0 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f by the [sqlite3_
2deb0 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 reset()] routine
2dec0 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 ..** ^Unbound pa
2ded0 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 rameters are int
2dee0 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c erpreted as NULL
2def0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
2df00 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 ite3_bind_* rout
2df10 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c ines return [SQL
2df20 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 ITE_OK] on succe
2df30 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 ss or an.** [err
2df40 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 or code] if anyt
2df50 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e hing goes wrong.
2df60 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f .** ^[SQLITE_TOO
2df70 42 49 47 5d 20 6d 69 67 68 74 20 62 65 20 72 65 BIG] might be re
2df80 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 73 69 turned if the si
2df90 7a 65 20 6f 66 20 61 20 73 74 72 69 6e 67 20 6f ze of a string o
2dfa0 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64 r BLOB.** exceed
2dfb0 73 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 s limits imposed
2dfc0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d by [sqlite3_lim
2dfd0 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 it]([SQLITE_LIMI
2dfe0 54 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a T_LENGTH]) or.**
2dff0 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e [SQLITE_MAX_LEN
2e000 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 GTH]..** ^[SQLIT
2e010 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 E_RANGE] is retu
2e020 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 rned if the para
2e030 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 meter.** index i
2e040 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 s out of range.
2e050 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d ^[SQLITE_NOMEM]
2e060 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 is returned if
2e070 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a malloc() fails..
2e080 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
2e090 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
2e0a0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d rameter_count()]
2e0b0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 ,.** [sqlite3_bi
2e0c0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d nd_parameter_nam
2e0d0 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 e()], and [sqlit
2e0e0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
2e0f0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 r_index()]..*/.S
2e100 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 QLITE_API int SQ
2e110 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
2e120 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 ite3_bind_blob(s
2e130 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
2e140 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 t, const void*,
2e150 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 int n, void(*)(v
2e160 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 oid*));.SQLITE_A
2e170 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 PI int SQLITE_ST
2e180 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 DCALL sqlite3_bi
2e190 6e 64 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 nd_blob64(sqlite
2e1a0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 3_stmt*, int, co
2e1b0 6e 73 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74 nst void*, sqlit
2e1c0 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 e3_uint64,.
2e1d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2e1e0 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a void(*)(void*
2e1f0 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 ));.SQLITE_API i
2e200 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c nt SQLITE_STDCAL
2e210 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 L sqlite3_bind_d
2e220 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 ouble(sqlite3_st
2e230 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 mt*, int, double
2e240 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
2e250 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
2e260 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e sqlite3_bind_in
2e270 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c t(sqlite3_stmt*,
2e280 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 int, int);.SQLI
2e290 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
2e2a0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
2e2b0 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 3_bind_int64(sql
2e2c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c ite3_stmt*, int,
2e2d0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b sqlite3_int64);
2e2e0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
2e2f0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
2e300 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c qlite3_bind_null
2e310 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
2e320 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 int);.SQLITE_API
2e330 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
2e340 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 ALL sqlite3_bind
2e350 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 _text(sqlite3_st
2e360 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 mt*,int,const ch
2e370 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a 29 28 ar*,int,void(*)(
2e380 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f void*));.SQLITE_
2e390 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 API int SQLITE_S
2e3a0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 TDCALL sqlite3_b
2e3b0 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 ind_text16(sqlit
2e3c0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 e3_stmt*, int, c
2e3d0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c onst void*, int,
2e3e0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 void(*)(void*))
2e3f0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
2e400 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
2e410 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
2e420 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 t64(sqlite3_stmt
2e430 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 *, int, const ch
2e440 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e ar*, sqlite3_uin
2e450 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 t64,.
2e460 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f vo
2e470 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e id(*)(void*), un
2e480 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f signed char enco
2e490 64 69 6e 67 29 3b 0a 53 51 4c 49 54 45 5f 41 50 ding);.SQLITE_AP
2e4a0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
2e4b0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e CALL sqlite3_bin
2e4c0 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f d_value(sqlite3_
2e4d0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 stmt*, int, cons
2e4e0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a t sqlite3_value*
2e4f0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
2e500 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
2e510 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 sqlite3_bind_ze
2e520 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 roblob(sqlite3_s
2e530 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e tmt*, int, int n
2e540 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
2e550 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
2e560 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 sqlite3_bind_ze
2e570 72 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 roblob64(sqlite3
2e580 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c _stmt*, int, sql
2e590 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 0a 2f ite3_uint64);../
2e5a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e *.** CAPI3REF: N
2e5b0 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 umber Of SQL Par
2e5c0 61 6d 65 74 65 72 73 0a 2a 2a 20 4d 45 54 48 4f ameters.** METHO
2e5d0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a D: sqlite3_stmt.
2e5e0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 **.** ^This rout
2e5f0 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 ine can be used
2e600 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 to find the numb
2e610 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d er of [SQL param
2e620 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b eters].** in a [
2e630 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2e640 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 nt]. SQL parame
2e650 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 ters are tokens
2e660 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 of the.** form "
2e670 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 ?", "?NNN", ":AA
2e680 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 A", "$AAA", or "
2e690 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65 @AAA" that serve
2e6a0 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 as.** placehold
2e6b0 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 ers for values t
2e6c0 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 hat are [sqlite3
2e6d0 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 _bind_blob | bou
2e6e0 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 nd].** to the pa
2e6f0 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 rameters at a la
2e700 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 ter time..**.**
2e710 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 ^(This routine a
2e720 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 ctually returns
2e730 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 the index of the
2e740 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d largest (rightm
2e750 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 ost).** paramete
2e760 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 r. For all forms
2e770 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 except ?NNN, th
2e780 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f is will correspo
2e790 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d nd to the.** num
2e7a0 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 ber of unique pa
2e7b0 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 rameters. If pa
2e7c0 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 rameters of the
2e7d0 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 ?NNN form are us
2e7e0 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 ed,.** there may
2e7f0 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 be gaps in the
2e800 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 list.)^.**.** Se
2e810 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 e also: [sqlite3
2e820 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 _bind_blob|sqlit
2e830 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b e3_bind()],.** [
2e840 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
2e850 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 ameter_name()],
2e860 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f and.** [sqlite3_
2e870 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 bind_parameter_i
2e880 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 ndex()]..*/.SQLI
2e890 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
2e8a0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
2e8b0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
2e8c0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 _count(sqlite3_s
2e8d0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 tmt*);../*.** CA
2e8e0 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 PI3REF: Name Of
2e8f0 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 A Host Parameter
2e900 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
2e910 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e te3_stmt.**.** ^
2e920 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 The sqlite3_bind
2e930 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 _parameter_name(
2e940 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 P,N) interface r
2e950 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 eturns.** the na
2e960 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b me of the N-th [
2e970 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 SQL parameter] i
2e980 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 n the [prepared
2e990 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a statement] P..**
2e9a0 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 ^(SQL parameter
2e9b0 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f s of the form "?
2e9c0 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f NNN" or ":AAA" o
2e9d0 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 r "@AAA" or "$AA
2e9e0 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d A".** have a nam
2e9f0 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 e which is the s
2ea00 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 tring "?NNN" or
2ea10 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 ":AAA" or "@AAA"
2ea20 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 or "$AAA".** re
2ea30 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 spectively..** I
2ea40 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 n other words, t
2ea50 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f he initial ":" o
2ea60 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 r "$" or "@" or
2ea70 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 "?".** is includ
2ea80 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 ed as part of th
2ea90 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 e name.)^.** ^Pa
2eaa0 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 rameters of the
2eab0 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 form "?" without
2eac0 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 a following int
2ead0 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d eger have no nam
2eae0 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 e.** and are ref
2eaf0 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d erred to as "nam
2eb00 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 eless" or "anony
2eb10 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 mous parameters"
2eb20 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 ..**.** ^The fir
2eb30 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 st host paramete
2eb40 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f r has an index o
2eb50 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a f 1, not 0..**.*
2eb60 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 * ^If the value
2eb70 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 N is out of rang
2eb80 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 e or if the N-th
2eb90 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a parameter is.**
2eba0 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 nameless, then
2ebb0 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 NULL is returned
2ebc0 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 . ^The returned
2ebd0 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c string is.** al
2ebe0 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e ways in UTF-8 en
2ebf0 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 coding even if t
2ec00 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 he named paramet
2ec10 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e er was.** origin
2ec20 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 ally specified a
2ec30 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c s UTF-16 in [sql
2ec40 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 ite3_prepare16()
2ec50 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ] or.** [sqlite3
2ec60 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
2ec70 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
2ec80 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f : [sqlite3_bind_
2ec90 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e blob|sqlite3_bin
2eca0 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 d()],.** [sqlite
2ecb0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
2ecc0 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a _count()], and.*
2ecd0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
2ece0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 parameter_index(
2ecf0 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 )]..*/.SQLITE_AP
2ed00 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 I const char *SQ
2ed10 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
2ed20 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
2ed30 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 ter_name(sqlite3
2ed40 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f _stmt*, int);../
2ed50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 *.** CAPI3REF: I
2ed60 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 ndex Of A Parame
2ed70 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e ter With A Given
2ed80 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a Name.** METHOD:
2ed90 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a sqlite3_stmt.**
2eda0 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 .** ^Return the
2edb0 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 index of an SQL
2edc0 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 parameter given
2edd0 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a its name. ^The.
2ede0 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 ** index value r
2edf0 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 eturned is suita
2ee00 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 ble for use as t
2ee10 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 he second.** par
2ee20 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 ameter to [sqlit
2ee30 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c e3_bind_blob|sql
2ee40 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e ite3_bind()]. ^
2ee50 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 A zero.** is ret
2ee60 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 urned if no matc
2ee70 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 hing parameter i
2ee80 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 s found. ^The p
2ee90 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 arameter.** name
2eea0 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 must be given i
2eeb0 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 n UTF-8 even if
2eec0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 the original sta
2eed0 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 tement.** was pr
2eee0 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d epared from UTF-
2eef0 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 16 text using [s
2ef00 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
2ef10 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 _v2()]..**.** Se
2ef20 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 e also: [sqlite3
2ef30 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 _bind_blob|sqlit
2ef40 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b e3_bind()],.** [
2ef50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
2ef60 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c ameter_count()],
2ef70 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and.** [sqlite3
2ef80 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
2ef90 6e 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 name()]..*/.SQLI
2efa0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
2efb0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
2efc0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
2efd0 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 _index(sqlite3_s
2efe0 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 tmt*, const char
2eff0 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a *zName);../*.**
2f000 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 CAPI3REF: Reset
2f010 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e All Bindings On
2f020 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 A Prepared Stat
2f030 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a ement.** METHOD:
2f040 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a sqlite3_stmt.**
2f050 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f .** ^Contrary to
2f060 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f the intuition o
2f070 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 f many, [sqlite3
2f080 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e _reset()] does n
2f090 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 ot reset.** the
2f0a0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c [sqlite3_bind_bl
2f0b0 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f ob | bindings] o
2f0c0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 n a [prepared st
2f0d0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 atement]..** ^Us
2f0e0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 e this routine t
2f0f0 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 o reset all host
2f100 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e parameters to N
2f110 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ULL..*/.SQLITE_A
2f120 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 PI int SQLITE_ST
2f130 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6c DCALL sqlite3_cl
2f140 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c ear_bindings(sql
2f150 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a ite3_stmt*);../*
2f160 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 .** CAPI3REF: Nu
2f170 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 mber Of Columns
2f180 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a In A Result Set.
2f190 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
2f1a0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 e3_stmt.**.** ^R
2f1b0 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 eturn the number
2f1c0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 of columns in t
2f1d0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 he result set re
2f1e0 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a turned by the.**
2f1f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2f200 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 ment]. ^This rou
2f210 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 tine returns 0 i
2f220 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 f pStmt is an SQ
2f230 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 L.** statement t
2f240 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 hat does not ret
2f250 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 urn data (for ex
2f260 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 ample an [UPDATE
2f270 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c ])..**.** See al
2f280 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 so: [sqlite3_dat
2f290 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 a_count()].*/.SQ
2f2a0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
2f2b0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
2f2c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 te3_column_count
2f2d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 (sqlite3_stmt *p
2f2e0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 Stmt);../*.** CA
2f2f0 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e PI3REF: Column N
2f300 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 ames In A Result
2f310 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 Set.** METHOD:
2f320 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a sqlite3_stmt.**.
2f330 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e ** ^These routin
2f340 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 es return the na
2f350 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 me assigned to a
2f360 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 particular colu
2f370 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 mn.** in the res
2f380 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 ult set of a [SE
2f390 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e LECT] statement.
2f3a0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 ^The sqlite3_c
2f3b0 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 olumn_name().**
2f3c0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
2f3d0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
2f3e0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
2f3f0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a UTF-8 string.**
2f400 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c and sqlite3_col
2f410 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 umn_name16() ret
2f420 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
2f430 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 o a zero-termina
2f440 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 ted.** UTF-16 st
2f450 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 ring. ^The firs
2f460 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 t parameter is t
2f470 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
2f480 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 tement].** that
2f490 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b implements the [
2f4a0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e SELECT] statemen
2f4b0 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 t. ^The second p
2f4c0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a arameter is the.
2f4d0 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 ** column number
2f4e0 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 . ^The leftmost
2f4f0 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 column is numbe
2f500 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 r 0..**.** ^The
2f510 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 returned string
2f520 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 pointer is valid
2f530 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 until either th
2f540 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
2f550 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 ement].** is des
2f560 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 troyed by [sqlit
2f570 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f e3_finalize()] o
2f580 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 r until the stat
2f590 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 ement is automat
2f5a0 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 ically.** reprep
2f5b0 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 ared by the firs
2f5c0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 t call to [sqlit
2f5d0 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 e3_step()] for a
2f5e0 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a particular run.
2f5f0 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 ** or until the
2f600 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 next call to.**
2f610 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e sqlite3_column_n
2f620 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 ame() or sqlite3
2f630 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 _column_name16()
2f640 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c on the same col
2f650 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 umn..**.** ^If s
2f660 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
2f670 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 fails during the
2f680 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 processing of e
2f690 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a ither routine.**
2f6a0 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 (for example du
2f6b0 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f ring a conversio
2f6c0 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 n from UTF-8 to
2f6d0 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a UTF-16) then a.*
2f6e0 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 * NULL pointer i
2f6f0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a s returned..**.*
2f700 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 * ^The name of a
2f710 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 result column i
2f720 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 s the value of t
2f730 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 he "AS" clause f
2f740 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d or.** that colum
2f750 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 n, if there is a
2f760 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 n AS clause. If
2f770 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 there is no AS
2f780 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 clause.** then t
2f790 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 he name of the c
2f7a0 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 olumn is unspeci
2f7b0 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 fied and may cha
2f7c0 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 nge from.** one
2f7d0 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 release of SQLit
2f7e0 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a e to the next..*
2f7f0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e /.SQLITE_API con
2f800 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f st char *SQLITE_
2f810 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
2f820 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 column_name(sqli
2f830 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e te3_stmt*, int N
2f840 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f );.SQLITE_API co
2f850 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 nst void *SQLITE
2f860 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
2f870 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 _column_name16(s
2f880 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
2f890 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 t N);../*.** CAP
2f8a0 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 I3REF: Source Of
2f8b0 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 Data In A Query
2f8c0 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f Result.** METHO
2f8d0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a D: sqlite3_stmt.
2f8e0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 **.** ^These rou
2f8f0 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 tines provide a
2f900 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 means to determi
2f910 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c ne the database,
2f920 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 table, and.** t
2f930 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 able column that
2f940 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f is the origin o
2f950 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 f a particular r
2f960 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a esult column in.
2f970 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 ** [SELECT] stat
2f980 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e ement..** ^The n
2f990 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 ame of the datab
2f9a0 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 ase or table or
2f9b0 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 column can be re
2f9c0 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 turned as.** eit
2f9d0 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 her a UTF-8 or U
2f9e0 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e TF-16 string. ^
2f9f0 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 The _database_ r
2fa00 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a outines return.*
2fa10 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e * the database n
2fa20 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f ame, the _table_
2fa30 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
2fa40 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c the table name,
2fa50 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 and.** the orig
2fa60 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 in_ routines ret
2fa70 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e urn the column n
2fa80 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 ame..** ^The ret
2fa90 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 urned string is
2faa0 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 valid until the
2fab0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2fac0 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 ent] is destroye
2fad0 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 d.** using [sqli
2fae0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 te3_finalize()]
2faf0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 or until the sta
2fb00 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 tement is automa
2fb10 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 tically.** repre
2fb20 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 pared by the fir
2fb30 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 st call to [sqli
2fb40 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 te3_step()] for
2fb50 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e a particular run
2fb60 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 .** or until the
2fb70 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f same informatio
2fb80 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a n is requested.*
2fb90 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 * again in a dif
2fba0 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e ferent encoding.
2fbb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 .**.** ^The name
2fbc0 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 s returned are t
2fbd0 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 he original un-a
2fbe0 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 liased names of
2fbf0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c the.** database,
2fc00 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 table, and colu
2fc10 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 mn..**.** ^The f
2fc20 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
2fc30 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 these interface
2fc40 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 s is a [prepared
2fc50 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 statement]..**
2fc60 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 ^These functions
2fc70 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 return informat
2fc80 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 ion about the Nt
2fc90 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 h result column
2fca0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 returned by.** t
2fcb0 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 he statement, wh
2fcc0 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 ere N is the sec
2fcd0 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 ond function arg
2fce0 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c ument..** ^The l
2fcf0 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 eft-most column
2fd00 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 is column 0 for
2fd10 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a these routines..
2fd20 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 **.** ^If the Nt
2fd30 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 h column returne
2fd40 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 d by the stateme
2fd50 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 nt is an express
2fd60 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 ion or.** subque
2fd70 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 ry and is not a
2fd80 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 column value, th
2fd90 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 en all of these
2fda0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e functions return
2fdb0 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 .** NULL. ^Thes
2fdc0 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 e routine might
2fdd0 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c also return NULL
2fde0 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c if a memory all
2fdf0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a ocation error.**
2fe00 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 occurs. ^Other
2fe10 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 wise, they retur
2fe20 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 n the name of th
2fe30 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 e attached datab
2fe40 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f ase, table,.** o
2fe50 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 r column that qu
2fe60 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d ery result colum
2fe70 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 n was extracted
2fe80 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 from..**.** ^As
2fe90 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 with all other S
2fea0 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 QLite APIs, thos
2feb0 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e e whose names en
2fec0 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 d with "16" retu
2fed0 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 rn.** UTF-16 enc
2fee0 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 oded strings and
2fef0 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 the other funct
2ff00 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d ions return UTF-
2ff10 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 8..**.** ^These
2ff20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 APIs are only av
2ff30 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c ailable if the l
2ff40 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 ibrary was compi
2ff50 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 led with the.**
2ff60 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 [SQLITE_ENABLE_C
2ff70 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 OLUMN_METADATA]
2ff80 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 C-preprocessor s
2ff90 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 ymbol..**.** If
2ffa0 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 two or more thre
2ffb0 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 ads call one or
2ffc0 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f more of these ro
2ffd0 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 utines against t
2ffe0 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 he same.** prepa
2fff0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e red statement an
30000 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 d column at the
30010 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 same time then t
30020 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a he results are.*
30030 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a * undefined..**.
30040 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 ** If two or mor
30050 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f e threads call o
30060 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 ne or more.** [s
30070 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 qlite3_column_da
30080 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f tabase_name | co
30090 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e lumn metadata in
300a0 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 terfaces].** for
300b0 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 the same [prepa
300c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 red statement] a
300d0 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e nd result column
300e0 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 .** at the same
300f0 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 time then the re
30100 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 sults are undefi
30110 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ned..*/.SQLITE_A
30120 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 PI const char *S
30130 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
30140 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 lite3_column_dat
30150 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 abase_name(sqlit
30160 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 e3_stmt*,int);.S
30170 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
30180 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 void *SQLITE_STD
30190 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c CALL sqlite3_col
301a0 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d umn_database_nam
301b0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 e16(sqlite3_stmt
301c0 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 *,int);.SQLITE_A
301d0 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 PI const char *S
301e0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
301f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 lite3_column_tab
30200 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f le_name(sqlite3_
30210 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 stmt*,int);.SQLI
30220 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 TE_API const voi
30230 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c d *SQLITE_STDCAL
30240 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e L sqlite3_column
30250 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 _table_name16(sq
30260 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
30270 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e ;.SQLITE_API con
30280 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f st char *SQLITE_
30290 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
302a0 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 column_origin_na
302b0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a me(sqlite3_stmt*
302c0 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 ,int);.SQLITE_AP
302d0 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 I const void *SQ
302e0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
302f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 ite3_column_orig
30300 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 in_name16(sqlite
30310 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 3_stmt*,int);../
30320 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
30330 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 eclared Datatype
30340 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 Of A Query Resu
30350 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 lt.** METHOD: sq
30360 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a lite3_stmt.**.**
30370 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72 ^(The first par
30380 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 ameter is a [pre
30390 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
303a0 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 ..** If this sta
303b0 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c tement is a [SEL
303c0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 ECT] statement a
303d0 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d nd the Nth colum
303e0 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 n of the.** retu
303f0 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 rned result set
30400 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d of that [SELECT]
30410 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 is a table colu
30420 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 mn (not an.** ex
30430 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 pression or subq
30440 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 uery) then the d
30450 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 eclared type of
30460 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c the table.** col
30470 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e umn is returned.
30480 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 )^ ^If the Nth
30490 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 column of the re
304a0 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a sult set is an.*
304b0 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 * expression or
304c0 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 subquery, then a
304d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 NULL pointer is
304e0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 returned..** ^T
304f0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 he returned stri
30500 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 ng is always UTF
30510 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a -8 encoded..**.*
30520 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c * ^(For example,
30530 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 given the datab
30540 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a ase schema:.**.*
30550 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 * CREATE TABLE t
30560 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 1(c1 VARIANT);.*
30570 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c *.** and the fol
30580 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 lowing statement
30590 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a to be compiled:
305a0 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 .**.** SELECT c1
305b0 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 + 1, c1 FROM t1
305c0 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 ;.**.** this rou
305d0 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 tine would retur
305e0 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 n the string "VA
305f0 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 RIANT" for the s
30600 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 econd result.**
30610 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 column (i==1), a
30620 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 nd a NULL pointe
30630 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 r for the first
30640 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 result column (i
30650 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 ==0).)^.**.** ^S
30660 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d QLite uses dynam
30670 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 ic run-time typi
30680 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 ng. ^So just be
30690 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a cause a column.*
306a0 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f * is declared to
306b0 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 contain a parti
306c0 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 cular type does
306d0 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 not mean that th
306e0 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 e.** data stored
306f0 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 in that column
30700 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 is of the declar
30710 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 ed type. SQLite
30720 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 is.** strongly
30730 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 typed, but the t
30740 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 yping is dynamic
30750 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 not static. ^T
30760 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 ype.** is associ
30770 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 ated with indivi
30780 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 dual values, not
30790 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 with the contai
307a0 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 ners.** used to
307b0 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 hold those value
307c0 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 s..*/.SQLITE_API
307d0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c const char *SQL
307e0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
307f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 te3_column_declt
30800 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ype(sqlite3_stmt
30810 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 *,int);.SQLITE_A
30820 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 PI const void *S
30830 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
30840 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 lite3_column_dec
30850 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f ltype16(sqlite3_
30860 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a stmt*,int);../*.
30870 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 ** CAPI3REF: Eva
30880 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 luate An SQL Sta
30890 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 tement.** METHOD
308a0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a : sqlite3_stmt.*
308b0 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 *.** After a [pr
308c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
308d0 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 ] has been prepa
308e0 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 red using either
308f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
30900 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 pare_v2()] or [s
30910 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
30920 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 _v2()] or one of
30930 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 the legacy.** i
30940 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 nterfaces [sqlit
30950 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 e3_prepare()] or
30960 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
30970 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e e16()], this fun
30980 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 ction.** must be
30990 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d called one or m
309a0 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 ore times to eva
309b0 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d luate the statem
309c0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 ent..**.** The d
309d0 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 etails of the be
309e0 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 havior of the sq
309f0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 lite3_step() int
30a00 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a erface depend.**
30a10 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 on whether the
30a20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 statement was pr
30a30 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 epared using the
30a40 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 newer "v2" inte
30a50 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 rface.** [sqlite
30a60 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
30a70 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 and [sqlite3_pre
30a80 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 pare16_v2()] or
30a90 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 the older legacy
30aa0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 .** interface [s
30ab0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 qlite3_prepare()
30ac0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 ] and [sqlite3_p
30ad0 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 repare16()]. Th
30ae0 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 e use of the.**
30af0 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 new "v2" interfa
30b00 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 ce is recommende
30b10 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 d for new applic
30b20 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c ations but the l
30b30 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 egacy.** interfa
30b40 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 ce will continue
30b50 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 to be supported
30b60 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 ..**.** ^In the
30b70 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 legacy interface
30b80 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c , the return val
30b90 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 ue will be eithe
30ba0 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c r [SQLITE_BUSY],
30bb0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 .** [SQLITE_DONE
30bc0 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c ], [SQLITE_ROW],
30bd0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c [SQLITE_ERROR],
30be0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 or [SQLITE_MISU
30bf0 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 SE]..** ^With th
30c00 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 e "v2" interface
30c10 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 , any of the oth
30c20 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 er [result codes
30c30 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 ] or.** [extende
30c40 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 d result codes]
30c50 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 might be returne
30c60 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a d as well..**.**
30c70 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 ^[SQLITE_BUSY]
30c80 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 means that the d
30c90 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 atabase engine w
30ca0 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 as unable to acq
30cb0 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 uire the.** data
30cc0 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 base locks it ne
30cd0 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f eds to do its jo
30ce0 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 b. ^If the stat
30cf0 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d ement is a [COMM
30d00 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 IT].** or occurs
30d10 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 outside of an e
30d20 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 xplicit transact
30d30 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 ion, then you ca
30d40 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 n retry the.** s
30d50 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 tatement. If th
30d60 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e e statement is n
30d70 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e ot a [COMMIT] an
30d80 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 d occurs within
30d90 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 an.** explicit t
30da0 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 ransaction then
30db0 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 you should rollb
30dc0 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 ack the transact
30dd0 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f ion before.** co
30de0 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 ntinuing..**.**
30df0 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d ^[SQLITE_DONE] m
30e00 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 eans that the st
30e10 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 atement has fini
30e20 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a shed executing.*
30e30 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 * successfully.
30e40 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 sqlite3_step()
30e50 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 should not be ca
30e60 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 lled again on th
30e70 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 is virtual.** ma
30e80 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 chine without fi
30e90 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c rst calling [sql
30ea0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f ite3_reset()] to
30eb0 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75 reset the virtu
30ec0 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 al.** machine ba
30ed0 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 ck to its initia
30ee0 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e l state..**.** ^
30ef0 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 If the SQL state
30f00 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 ment being execu
30f10 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 ted returns any
30f20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 data, then [SQLI
30f30 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 TE_ROW].** is re
30f40 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 turned each time
30f50 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 a new row of da
30f60 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 ta is ready for
30f70 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 processing by th
30f80 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 e.** caller. The
30f90 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 values may be a
30fa0 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 ccessed using th
30fb0 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 e [column access
30fc0 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 functions]..**
30fd0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 sqlite3_step() i
30fe0 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 s called again t
30ff0 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e o retrieve the n
31000 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e ext row of data.
31010 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f .**.** ^[SQLITE_
31020 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 ERROR] means tha
31030 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 t a run-time err
31040 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f or (such as a co
31050 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c nstraint.** viol
31060 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 ation) has occur
31070 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 red. sqlite3_st
31080 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 ep() should not
31090 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 be called again
310a0 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f on.** the VM. Mo
310b0 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d re information m
310c0 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 ay be found by c
310d0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
310e0 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 errmsg()]..** ^W
310f0 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 ith the legacy i
31100 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 nterface, a more
31110 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 specific error
31120 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c code (for exampl
31130 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e e,.** [SQLITE_IN
31140 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 TERRUPT], [SQLIT
31150 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 E_SCHEMA], [SQLI
31160 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 TE_CORRUPT], and
31170 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 so forth).** ca
31180 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 n be obtained by
31190 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 calling [sqlite
311a0 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 3_reset()] on th
311b0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 e.** [prepared s
311c0 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 tatement]. ^In
311d0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 the "v2" interfa
311e0 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 ce,.** the more
311f0 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 specific error c
31200 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 ode is returned
31210 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 directly by sqli
31220 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a te3_step()..**.*
31230 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 * [SQLITE_MISUSE
31240 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 ] means that the
31250 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 this routine wa
31260 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f s called inappro
31270 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 priately..** Per
31280 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c haps it was call
31290 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 ed on a [prepare
312a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 d statement] tha
312b0 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 t has.** already
312c0 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 been [sqlite3_f
312d0 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 inalize | finali
312e0 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 zed] or on one t
312f0 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 hat had.** previ
31300 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b ously returned [
31310 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 SQLITE_ERROR] or
31320 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 [SQLITE_DONE].
31330 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 Or it could.**
31340 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 be the case that
31350 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 the same databa
31360 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
31370 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 being used by t
31380 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 wo or.** more th
31390 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d reads at the sam
313a0 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 e moment in time
313b0 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 ..**.** For all
313c0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
313d0 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 te up to and inc
313e0 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c luding 3.6.23.1,
313f0 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 a call to.** [s
31400 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
31410 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74 was required aft
31420 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 er sqlite3_step(
31430 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 ) returned anyth
31440 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 ing.** other tha
31450 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 n [SQLITE_ROW] b
31460 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 efore any subseq
31470 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 uent invocation
31480 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 of.** sqlite3_st
31490 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 ep(). Failure t
314a0 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 o reset the prep
314b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 ared statement u
314c0 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 sing .** [sqlite
314d0 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 3_reset()] would
314e0 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 result in an [S
314f0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 QLITE_MISUSE] re
31500 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c turn from.** sql
31510 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 ite3_step(). Bu
31520 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20 t after version
31530 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 3.6.23.1, sqlite
31540 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 3_step() began.*
31550 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 * calling [sqlit
31560 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f e3_reset()] auto
31570 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 matically in thi
31580 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 s circumstance r
31590 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 ather.** than re
315a0 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f turning [SQLITE_
315b0 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 MISUSE]. This i
315c0 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 s not considered
315d0 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 a compatibility
315e0 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 .** break becaus
315f0 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f e any applicatio
31600 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65 n that ever rece
31610 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d ives an SQLITE_M
31620 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 ISUSE error.** i
31630 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 s broken by defi
31640 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 nition. The [SQ
31650 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 LITE_OMIT_AUTORE
31660 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d SET] compile-tim
31670 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 e option.** can
31680 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f be used to resto
31690 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 re the legacy be
316a0 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 havior..**.** <b
316b0 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 >Goofy Interface
316c0 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 Alert:</b> In t
316d0 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 he legacy interf
316e0 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 ace, the sqlite3
316f0 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 _step().** API a
31700 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 lways returns a
31710 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f generic error co
31720 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f de, [SQLITE_ERRO
31730 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e R], following an
31740 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 y.** error other
31750 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 than [SQLITE_BU
31760 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f SY] and [SQLITE_
31770 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 MISUSE]. You mu
31780 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 st call.** [sqli
31790 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 te3_reset()] or
317a0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
317b0 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f e()] in order to
317c0 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 find one of the
317d0 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 .** specific [er
317e0 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 ror codes] that
317f0 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73 better describes
31800 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 the error..** W
31810 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 e admit that thi
31820 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 s is a goofy des
31830 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 ign. The proble
31840 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 m has been fixed
31850 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 .** with the "v2
31860 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 " interface. If
31870 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c you prepare all
31880 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 of your SQL sta
31890 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 tements.** using
318a0 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 either [sqlite3
318b0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f _prepare_v2()] o
318c0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 r [sqlite3_prepa
318d0 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 re16_v2()] inste
318e0 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 ad.** of the leg
318f0 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 acy [sqlite3_pre
31900 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c pare()] and [sql
31910 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 ite3_prepare16()
31920 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a ] interfaces,.**
31930 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 then the more s
31940 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 pecific [error c
31950 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e odes] are return
31960 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 ed directly.** b
31970 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 y sqlite3_step()
31980 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 . The use of th
31990 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 e "v2" interface
319a0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e is recommended.
319b0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
319c0 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c nt SQLITE_STDCAL
319d0 4c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 L sqlite3_step(s
319e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a qlite3_stmt*);..
319f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
31a00 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e Number of column
31a10 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 s in a result se
31a20 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c t.** METHOD: sql
31a30 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 ite3_stmt.**.**
31a40 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 ^The sqlite3_dat
31a50 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 a_count(P) inter
31a60 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 face returns the
31a70 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d number of colum
31a80 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 ns in the.** cur
31a90 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 rent row of the
31aa0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 result set of [p
31ab0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
31ac0 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 t] P..** ^If pre
31ad0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 pared statement
31ae0 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 P does not have
31af0 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f results ready to
31b00 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 return.** (via
31b10 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 calls to the [sq
31b20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 lite3_column_int
31b30 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d | sqlite3_colum
31b40 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 n_*()] of.** int
31b50 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 erfaces) then sq
31b60 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 lite3_data_count
31b70 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a (P) returns 0..*
31b80 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 * ^The sqlite3_d
31b90 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 ata_count(P) rou
31ba0 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e tine also return
31bb0 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 s 0 if P is a NU
31bc0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e LL pointer..** ^
31bd0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 The sqlite3_data
31be0 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e _count(P) routin
31bf0 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 e returns 0 if t
31c00 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c he previous call
31c10 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
31c20 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 step](P) returne
31c30 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e d [SQLITE_DONE].
31c40 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 ^The sqlite3_d
31c50 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 ata_count(P).**
31c60 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d will return non-
31c70 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 zero if previous
31c80 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
31c90 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 3_step](P) retur
31ca0 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 ned.** [SQLITE_R
31cb0 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 OW], except in t
31cc0 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b he case of the [
31cd0 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 PRAGMA increment
31ce0 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 al_vacuum].** wh
31cf0 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 ere it always re
31d00 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 turns zero since
31d10 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 each step of th
31d20 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a at multi-step.**
31d30 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 pragma returns
31d40 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 0 columns of dat
31d50 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 a..**.** See als
31d60 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 o: [sqlite3_colu
31d70 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 mn_count()].*/.S
31d80 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 QLITE_API int SQ
31d90 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
31da0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 ite3_data_count(
31db0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 sqlite3_stmt *pS
31dc0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 tmt);../*.** CAP
31dd0 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 I3REF: Fundament
31de0 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 al Datatypes.**
31df0 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 KEYWORDS: SQLITE
31e00 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 _TEXT.**.** ^(Ev
31e10 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c ery value in SQL
31e20 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 ite has one of f
31e30 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 ive fundamental
31e40 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a datatypes:.**.**
31e50 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 <ul>.** <li> 64
31e60 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 -bit signed inte
31e70 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 ger.** <li> 64-b
31e80 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 it IEEE floating
31e90 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a point number.**
31ea0 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 <li> string.**
31eb0 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 <li> BLOB.** <li
31ec0 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 > NULL.** </ul>)
31ed0 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f ^.**.** These co
31ee0 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 nstants are code
31ef0 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 s for each of th
31f00 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a ose types..**.**
31f10 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 Note that the S
31f20 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 QLITE_TEXT const
31f30 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 ant was also use
31f40 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 d in SQLite vers
31f50 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 ion 2.** for a c
31f60 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 ompletely differ
31f70 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f ent meaning. So
31f80 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b ftware that link
31f90 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a s against both.*
31fa0 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e * SQLite version
31fb0 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 2 and SQLite ve
31fc0 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 rsion 3 should u
31fd0 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c se SQLITE3_TEXT,
31fe0 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 not.** SQLITE_T
31ff0 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 EXT..*/.#define
32000 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 SQLITE_INTEGER
32010 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
32020 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 _FLOAT 2.#def
32030 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 ine SQLITE_BLOB
32040 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4.#define SQ
32050 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a LITE_NULL 5.
32060 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 #ifdef SQLITE_TE
32070 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 XT.# undef SQLIT
32080 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 E_TEXT.#else.# d
32090 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 efine SQLITE_TEX
320a0 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 T 3.#endif.#
320b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 define SQLITE3_T
320c0 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a EXT 3../*.**
320d0 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c CAPI3REF: Resul
320e0 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 t Values From A
320f0 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 Query.** KEYWORD
32100 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 S: {column acces
32110 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 s functions}.**
32120 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f METHOD: sqlite3_
32130 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 stmt.**.** ^Thes
32140 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 e routines retur
32150 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 n information ab
32160 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c out a single col
32170 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 umn of the curre
32180 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 nt.** result row
32190 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 of a query. ^I
321a0 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65 n every case the
321b0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
321c0 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 is a pointer.**
321d0 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 to the [prepared
321e0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 statement] that
321f0 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 is being evalua
32200 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 ted (the [sqlite
32210 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 3_stmt*].** that
32220 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 was returned fr
32230 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 om [sqlite3_prep
32240 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 are_v2()] or one
32250 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 of its variants
32260 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 ).** and the sec
32270 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ond argument is
32280 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 the index of the
32290 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 column for whic
322a0 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a h information.**
322b0 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 should be retur
322c0 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f ned. ^The leftmo
322d0 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 st column of the
322e0 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 result set has
322f0 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 the index 0..**
32300 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 ^The number of c
32310 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 olumns in the re
32320 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 sult can be dete
32330 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 rmined using.**
32340 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
32350 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 count()]..**.**
32360 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 If the SQL state
32370 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 ment does not cu
32380 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f rrently point to
32390 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 a valid row, or
323a0 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d if the.** colum
323b0 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f n index is out o
323c0 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 f range, the res
323d0 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 ult is undefined
323e0 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 ..** These routi
323f0 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 nes may only be
32400 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 called when the
32410 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c most recent call
32420 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
32430 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 step()] has retu
32440 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 rned [SQLITE_ROW
32450 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a ] and neither.**
32460 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
32470 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f )] nor [sqlite3_
32480 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 finalize()] have
32490 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 been called sub
324a0 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 sequently..** If
324b0 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f any of these ro
324c0 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 utines are calle
324d0 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 d after [sqlite3
324e0 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 _reset()] or.**
324f0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
32500 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 e()] or after [s
32510 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 qlite3_step()] h
32520 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 as returned.** s
32530 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 omething other t
32540 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d han [SQLITE_ROW]
32550 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 , the results ar
32560 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 e undefined..**
32570 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 If [sqlite3_step
32580 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
32590 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c reset()] or [sql
325a0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
325b0 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 .** are called f
325c0 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 rom a different
325d0 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 thread while any
325e0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e of these routin
325f0 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e es.** are pendin
32600 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 g, then the resu
32610 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 lts are undefine
32620 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 d..**.** ^The sq
32630 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 lite3_column_typ
32640 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 e() routine retu
32650 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 rns the.** [SQLI
32660 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 TE_INTEGER | dat
32670 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 atype code] for
32680 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 the initial data
32690 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 type.** of the
326a0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 result column.
326b0 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 ^The returned va
326c0 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 lue is one of [S
326d0 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a QLITE_INTEGER],.
326e0 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 ** [SQLITE_FLOAT
326f0 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d ], [SQLITE_TEXT]
32700 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c , [SQLITE_BLOB],
32710 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c or [SQLITE_NULL
32720 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a ]. The value.**
32730 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c returned by sql
32740 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 ite3_column_type
32750 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 () is only meani
32760 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 ngful if no type
32770 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 .** conversions
32780 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 have occurred as
32790 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 described below
327a0 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20 . After a type
327b0 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 conversion,.** t
327c0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
327d0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c d by sqlite3_col
327e0 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e umn_type() is un
327f0 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 defined. Future
32800 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 .** versions of
32810 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 SQLite may chang
32820 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f e the behavior o
32830 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e f sqlite3_column
32840 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f _type().** follo
32850 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 wing a type conv
32860 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 ersion..**.** ^I
32870 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 f the result is
32880 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 a BLOB or UTF-8
32890 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 string then the
328a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
328b0 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e ytes().** routin
328c0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 e returns the nu
328d0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e mber of bytes in
328e0 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 that BLOB or st
328f0 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 ring..** ^If the
32900 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 result is a UTF
32910 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e -16 string, then
32920 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
32930 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 bytes() converts
32940 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 .** the string t
32950 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e o UTF-8 and then
32960 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
32970 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a ber of bytes..**
32980 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 ^If the result
32990 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c is a numeric val
329a0 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f ue then sqlite3_
329b0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 column_bytes() u
329c0 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ses.** [sqlite3_
329d0 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 snprintf()] to c
329e0 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 onvert that valu
329f0 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 e to a UTF-8 str
32a00 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a ing and returns.
32a10 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ** the number of
32a20 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 bytes in that s
32a30 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 tring..** ^If th
32a40 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c e result is NULL
32a50 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 , then sqlite3_c
32a60 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 olumn_bytes() re
32a70 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a turns zero..**.*
32a80 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 * ^If the result
32a90 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 is a BLOB or UT
32aa0 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e F-16 string then
32ab0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c the sqlite3_col
32ac0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a umn_bytes16().**
32ad0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
32ae0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
32af0 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f ytes in that BLO
32b00 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 B or string..**
32b10 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 ^If the result i
32b20 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 s a UTF-8 string
32b30 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 , then sqlite3_c
32b40 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 olumn_bytes16()
32b50 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 converts.** the
32b60 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 string to UTF-16
32b70 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e and then return
32b80 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
32b90 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 bytes..** ^If th
32ba0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 e result is a nu
32bb0 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e meric value then
32bc0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
32bd0 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a bytes16() uses.*
32be0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 * [sqlite3_snpri
32bf0 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 ntf()] to conver
32c00 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 t that value to
32c10 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 a UTF-16 string
32c20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 and returns.** t
32c30 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
32c40 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e es in that strin
32c50 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 g..** ^If the re
32c60 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 sult is NULL, th
32c70 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d en sqlite3_colum
32c80 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 75 n_bytes16() retu
32c90 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 rns zero..**.**
32ca0 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 ^The values retu
32cb0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 rned by [sqlite3
32cc0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d _column_bytes()]
32cd0 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 and .** [sqlite
32ce0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
32cf0 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 ()] do not inclu
32d00 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d de the zero term
32d10 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 inators at the e
32d20 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 nd.** of the str
32d30 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 ing. ^For clari
32d40 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 ty: the values r
32d50 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 eturned by.** [s
32d60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
32d70 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 tes()] and [sqli
32d80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
32d90 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 16()] are the nu
32da0 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 mber of.** bytes
32db0 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 in the string,
32dc0 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f not the number o
32dd0 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a f characters..**
32de0 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 .** ^Strings ret
32df0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 urned by sqlite3
32e00 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 _column_text() a
32e10 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nd sqlite3_colum
32e20 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 n_text16(),.** e
32e30 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 ven empty string
32e40 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 s, are always ze
32e50 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 ro-terminated.
32e60 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 ^The return.** v
32e70 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 alue from sqlite
32e80 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 3_column_blob()
32e90 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 for a zero-lengt
32ea0 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c h BLOB is a NULL
32eb0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 pointer..**.**
32ec0 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 <b>Warning:</b>
32ed0 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 ^The object retu
32ee0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 rned by [sqlite3
32ef0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d _column_value()]
32f00 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f is an.** [unpro
32f10 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
32f20 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49 alue] object. I
32f30 6e 20 61 20 6d 75 6c 74 69 74 68 72 65 61 64 65 n a multithreade
32f40 64 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a d environment,.*
32f50 2a 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 * an unprotected
32f60 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
32f70 62 6a 65 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62 bject may only b
32f80 65 20 75 73 65 64 20 73 61 66 65 6c 79 20 77 69 e used safely wi
32f90 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 th.** [sqlite3_b
32fa0 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 ind_value()] and
32fb0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 [sqlite3_result
32fc0 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 _value()]..** If
32fd0 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 the [unprotecte
32fe0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d d sqlite3_value]
32ff0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 object returned
33000 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f by.** [sqlite3_
33010 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 column_value()]
33020 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f is used in any o
33030 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 ther way, includ
33040 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 ing calls.** to
33050 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 routines like [s
33060 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 qlite3_value_int
33070 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 ()], [sqlite3_va
33080 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 lue_text()],.**
33090 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 or [sqlite3_valu
330a0 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 20 e_bytes()], the
330b0 62 65 68 61 76 69 6f 72 20 69 73 20 6e 6f 74 20 behavior is not
330c0 74 68 72 65 61 64 73 61 66 65 2e 0a 2a 2a 0a 2a threadsafe..**.*
330d0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
330e0 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 attempt to conv
330f0 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 ert the value wh
33100 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e ere appropriate.
33110 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c ^For.** exampl
33120 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e e, if the intern
33130 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f al representatio
33140 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 n is FLOAT and a
33150 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 text result.**
33160 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 is requested, [s
33170 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
33180 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 )] is used inter
33190 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d nally to perform
331a0 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 the.** conversi
331b0 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 on automatically
331c0 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 . ^(The followi
331d0 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 ng table details
331e0 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 the conversions
331f0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 .** that are app
33200 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f lied:.**.** <blo
33210 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 ckquote>.** <tab
33220 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a le border="1">.*
33230 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 * <tr><th> Inter
33240 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e nal<br>Type <th>
33250 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 Requested<br>Ty
33260 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 pe <th> Convers
33270 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 ion.**.** <tr><t
33280 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e d> NULL <td>
33290 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 INTEGER <td>
332a0 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c Result is 0.** <
332b0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 tr><td> NULL
332c0 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 <td> FLOAT
332d0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 <td> Result is 0
332e0 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 .0.** <tr><td>
332f0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 NULL <td> T
33300 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 EXT <td> Resu
33310 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 lt is a NULL poi
33320 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e nter.** <tr><td>
33330 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 NULL <td>
33340 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 BLOB <td> Re
33350 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 sult is a NULL p
33360 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 ointer.** <tr><t
33370 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e d> INTEGER <td>
33380 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 FLOAT <td>
33390 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 Convert from int
333a0 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a eger to float.**
333b0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 <tr><td> INTEGE
333c0 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 R <td> TEXT
333d0 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e <td> ASCII ren
333e0 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e dering of the in
333f0 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 teger.** <tr><td
33400 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 > INTEGER <td>
33410 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 BLOB <td> S
33420 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e ame as INTEGER->
33430 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e TEXT.** <tr><td>
33440 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 FLOAT <td> I
33450 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 NTEGER <td> [C
33460 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a AST] to INTEGER.
33470 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f ** <tr><td> FLO
33480 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 AT <td> TEXT
33490 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 <td> ASCII r
334a0 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 endering of the
334b0 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 float.** <tr><td
334c0 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 > FLOAT <td>
334d0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b BLOB <td> [
334e0 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a CAST] to BLOB.**
334f0 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 <tr><td> TEXT
33500 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 <td> INTEGER
33510 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f <td> [CAST] to
33520 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e INTEGER.** <tr>
33530 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 <td> TEXT <t
33540 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 d> FLOAT <td
33550 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c > [CAST] to REAL
33560 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 .** <tr><td> TE
33570 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f XT <td> BLO
33580 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 B <td> No cha
33590 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 nge.** <tr><td>
335a0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e BLOB <td> IN
335b0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 TEGER <td> [CA
335c0 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a ST] to INTEGER.*
335d0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 * <tr><td> BLOB
335e0 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 <td> FLOAT
335f0 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 <td> [CAST] t
33600 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 o REAL.** <tr><t
33610 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e d> BLOB <td>
33620 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 TEXT <td>
33630 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 Add a zero termi
33640 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a nator if needed.
33650 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c ** </table>.** <
33660 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a /blockquote>)^.*
33670 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 *.** Note that w
33680 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 hen type convers
33690 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e ions occur, poin
336a0 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 ters returned by
336b0 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 prior.** calls
336c0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d to sqlite3_colum
336d0 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 n_blob(), sqlite
336e0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 3_column_text(),
336f0 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 and/or.** sqlit
33700 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
33710 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 () may be invali
33720 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 dated..** Type c
33730 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 onversions and p
33740 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 ointer invalidat
33750 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 ions might occur
33760 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f .** in the follo
33770 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a wing cases:.**.*
33780 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 * <ul>.** <li> T
33790 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 he initial conte
337a0 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 nt is a BLOB and
337b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
337c0 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 text() or.**
337d0 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e sqlite3_column
337e0 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c _text16() is cal
337f0 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 led. A zero-ter
33800 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a minator might.**
33810 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 need to be
33820 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 added to the st
33830 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c ring.</li>.** <l
33840 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 i> The initial c
33850 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 ontent is UTF-8
33860 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 text and sqlite3
33870 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
33880 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c ) or.** sql
33890 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
338a0 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 16() is called.
338b0 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 The content mus
338c0 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a t be converted.*
338d0 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 * to UTF-16
338e0 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 .</li>.** <li> T
338f0 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 he initial conte
33900 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 nt is UTF-16 tex
33910 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f t and sqlite3_co
33920 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a lumn_bytes() or.
33930 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f ** sqlite3_
33940 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 column_text() is
33950 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f called. The co
33960 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f ntent must be co
33970 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 nverted.**
33980 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a to UTF-8.</li>.*
33990 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 * </ul>.**.** ^C
339a0 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 onversions betwe
339b0 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 en UTF-16be and
339c0 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 UTF-16le are alw
339d0 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 ays done in plac
339e0 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 e and do.** not
339f0 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 invalidate a pri
33a00 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 or pointer, thou
33a10 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 gh of course the
33a20 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 content of the
33a30 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 buffer.** that t
33a40 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 he prior pointer
33a50 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c references will
33a60 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 have been modif
33a70 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 ied. Other kind
33a80 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 s.** of conversi
33a90 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 on are done in p
33aa0 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 lace when it is
33ab0 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f possible, but so
33ac0 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 metimes they.**
33ad0 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 are not possible
33ae0 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 and in those ca
33af0 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 ses prior pointe
33b00 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 rs are invalidat
33b10 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 ed..**.** The sa
33b20 66 65 73 74 20 70 6f 6c 69 63 79 20 69 73 20 74 fest policy is t
33b30 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 o invoke these r
33b40 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e outines.** in on
33b50 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 e of the followi
33b60 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c ng ways:.**.** <
33b70 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 ul>.** <li>sqli
33b80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
33b90 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 ) followed by sq
33ba0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
33bb0 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c es()</li>.** <l
33bc0 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e i>sqlite3_column
33bd0 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 _blob() followed
33be0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 by sqlite3_colu
33bf0 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a mn_bytes()</li>.
33c00 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f ** <li>sqlite3_
33c10 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 column_text16()
33c20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 followed by sqli
33c30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
33c40 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 16()</li>.** </u
33c50 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 l>.**.** In othe
33c60 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f r words, you sho
33c70 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 uld call sqlite3
33c80 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a _column_text(),.
33c90 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d ** sqlite3_colum
33ca0 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c n_blob(), or sql
33cb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
33cc0 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 16() first to fo
33cd0 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a rce the result.*
33ce0 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 * into the desir
33cf0 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 ed format, then
33d00 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 invoke sqlite3_c
33d10 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 olumn_bytes() or
33d20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 .** sqlite3_colu
33d30 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 mn_bytes16() to
33d40 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 find the size of
33d50 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f the result. Do
33d60 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a not mix calls.*
33d70 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c * to sqlite3_col
33d80 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 umn_text() or sq
33d90 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f lite3_column_blo
33da0 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 b() with calls t
33db0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c o.** sqlite3_col
33dc0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 umn_bytes16(), a
33dd0 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 nd do not mix ca
33de0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 lls to sqlite3_c
33df0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a olumn_text16().*
33e00 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 * with calls to
33e10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
33e20 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ytes()..**.** ^T
33e30 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 he pointers retu
33e40 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 rned are valid u
33e50 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 ntil a type conv
33e60 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 ersion occurs as
33e70 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 .** described ab
33e80 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 ove, or until [s
33e90 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f qlite3_step()] o
33ea0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 r [sqlite3_reset
33eb0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 ()] or.** [sqlit
33ec0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 e3_finalize()] i
33ed0 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 s called. ^The
33ee0 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 memory space use
33ef0 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 d to hold string
33f00 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 s.** and BLOBs i
33f10 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 s freed automati
33f20 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 65 6d 3e 6e cally. Do <em>n
33f30 6f 74 3c 2f 65 6d 3e 20 70 61 73 73 20 74 68 65 ot</em> pass the
33f40 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e pointers return
33f50 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 ed.** from [sqli
33f60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 te3_column_blob(
33f70 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c )], [sqlite3_col
33f80 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 umn_text()], etc
33f90 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 . into.** [sqlit
33fa0 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a e3_free()]..**.*
33fb0 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 * ^(If a memory
33fc0 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 allocation error
33fd0 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 occurs during t
33fe0 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 he evaluation of
33ff0 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 any.** of these
34000 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 routines, a def
34010 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 ault value is re
34020 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 turned. The def
34030 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 ault value.** is
34040 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 either the inte
34050 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 ger 0, the float
34060 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 ing point number
34070 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 0.0, or a NULL.
34080 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 ** pointer. Sub
34090 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f sequent calls to
340a0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 [sqlite3_errcod
340b0 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e e()] will return
340c0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 .** [SQLITE_NOME
340d0 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f M].)^.*/.SQLITE_
340e0 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a API const void *
340f0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
34100 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c qlite3_column_bl
34110 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a ob(sqlite3_stmt*
34120 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c , int iCol);.SQL
34130 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 ITE_API int SQLI
34140 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
34150 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
34160 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
34170 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 nt iCol);.SQLITE
34180 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f _API int SQLITE_
34190 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
341a0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 column_bytes16(s
341b0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
341c0 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f t iCol);.SQLITE_
341d0 41 50 49 20 64 6f 75 62 6c 65 20 53 51 4c 49 54 API double SQLIT
341e0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
341f0 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 3_column_double(
34200 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
34210 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 nt iCol);.SQLITE
34220 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f _API int SQLITE_
34230 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
34240 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 column_int(sqlit
34250 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
34260 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 ol);.SQLITE_API
34270 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 53 51 sqlite3_int64 SQ
34280 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
34290 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 ite3_column_int6
342a0 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 4(sqlite3_stmt*,
342b0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 int iCol);.SQLI
342c0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 TE_API const uns
342d0 69 67 6e 65 64 20 63 68 61 72 20 2a 53 51 4c 49 igned char *SQLI
342e0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
342f0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 e3_column_text(s
34300 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
34310 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f t iCol);.SQLITE_
34320 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a API const void *
34330 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
34340 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
34350 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d xt16(sqlite3_stm
34360 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 t*, int iCol);.S
34370 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 QLITE_API int SQ
34380 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
34390 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 ite3_column_type
343a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
343b0 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 int iCol);.SQLIT
343c0 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 76 61 E_API sqlite3_va
343d0 6c 75 65 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 lue *SQLITE_STDC
343e0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ALL sqlite3_colu
343f0 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 mn_value(sqlite3
34400 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
34410 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
34420 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 EF: Destroy A Pr
34430 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 epared Statement
34440 20 4f 62 6a 65 63 74 0a 2a 2a 20 44 45 53 54 52 Object.** DESTR
34450 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 UCTOR: sqlite3_s
34460 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 tmt.**.** ^The s
34470 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
34480 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 ) function is ca
34490 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 lled to delete a
344a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
344b0 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 ment]..** ^If th
344c0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 e most recent ev
344d0 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 aluation of the
344e0 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e statement encoun
344f0 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a tered no errors.
34500 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 ** or if the sta
34510 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 tement is never
34520 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 been evaluated,
34530 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e then sqlite3_fin
34540 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a alize() returns.
34550 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e ** SQLITE_OK. ^
34560 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 If the most rece
34570 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 nt evaluation of
34580 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 statement S fai
34590 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c led, then.** sql
345a0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 ite3_finalize(S)
345b0 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 returns the app
345c0 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 ropriate [error
345d0 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 code] or.** [ext
345e0 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 ended error code
345f0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 ]..**.** ^The sq
34600 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 lite3_finalize(S
34610 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 ) routine can be
34620 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 called at any p
34630 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 oint during.** t
34640 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 he life cycle of
34650 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
34660 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f ment] S:.** befo
34670 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 re statement S i
34680 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 s ever evaluated
34690 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f , after.** one o
346a0 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 r more calls to
346b0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
346c0 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 ], or after any
346d0 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 call.** to [sqli
346e0 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 te3_step()] rega
346f0 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 rdless of whethe
34700 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 r or not the sta
34710 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f tement has.** co
34720 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f mpleted executio
34730 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 n..**.** ^Invoki
34740 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c ng sqlite3_final
34750 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 ize() on a NULL
34760 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 pointer is a har
34770 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a mless no-op..**.
34780 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 ** The applicati
34790 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 on must finalize
347a0 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 every [prepared
347b0 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f statement] in o
347c0 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a rder to avoid.**
347d0 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e resource leaks.
347e0 20 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f It is a grievo
347f0 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 us error for the
34800 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 application to
34810 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 try to use.** a
34820 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
34830 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 nt after it has
34840 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 been finalized.
34850 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 Any use of a pr
34860 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d epared.** statem
34870 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 ent after it has
34880 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 been finalized
34890 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e can result in un
348a0 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 defined and.** u
348b0 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 ndesirable behav
348c0 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66 ior such as segf
348d0 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 aults and heap c
348e0 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 orruption..*/.SQ
348f0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
34900 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
34910 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c te3_finalize(sql
34920 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 ite3_stmt *pStmt
34930 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
34940 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 EF: Reset A Prep
34950 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f ared Statement O
34960 62 6a 65 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a bject.** METHOD:
34970 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a sqlite3_stmt.**
34980 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
34990 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e reset() function
349a0 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 is called to re
349b0 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 set a [prepared
349c0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 statement].** ob
349d0 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 ject back to its
349e0 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 initial state,
349f0 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 ready to be re-e
34a00 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 xecuted..** ^Any
34a10 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 SQL statement v
34a20 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 ariables that ha
34a30 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 d values bound t
34a40 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 o them using.**
34a50 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e the [sqlite3_bin
34a60 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 d_blob | sqlite3
34a70 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 _bind_*() API] r
34a80 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 etain their valu
34a90 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 es..** Use [sqli
34aa0 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e te3_clear_bindin
34ab0 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 gs()] to reset t
34ac0 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a he bindings..**.
34ad0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 ** ^The [sqlite3
34ae0 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 _reset(S)] inter
34af0 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 face resets the
34b00 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
34b10 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 ent] S.** back t
34b20 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 o the beginning
34b30 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a of its program..
34b40 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f **.** ^If the mo
34b50 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 st recent call t
34b60 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 o [sqlite3_step(
34b70 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b S)] for the.** [
34b80 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
34b90 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b nt] S returned [
34ba0 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b SQLITE_ROW] or [
34bb0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a SQLITE_DONE],.**
34bc0 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f or if [sqlite3_
34bd0 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 step(S)] has nev
34be0 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 er before been c
34bf0 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 alled on S,.** t
34c00 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 hen [sqlite3_res
34c10 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b et(S)] returns [
34c20 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a SQLITE_OK]..**.*
34c30 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 * ^If the most r
34c40 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 ecent call to [s
34c50 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 qlite3_step(S)]
34c60 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 for the.** [prep
34c70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
34c80 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 S indicated an e
34c90 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 rror, then.** [s
34ca0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d qlite3_reset(S)]
34cb0 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 returns an appr
34cc0 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 opriate [error c
34cd0 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ode]..**.** ^The
34ce0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
34cf0 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f S)] interface do
34d00 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 es not change th
34d10 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 e values.** of a
34d20 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ny [sqlite3_bind
34d30 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 _blob|bindings]
34d40 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 on the [prepared
34d50 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a statement] S..*
34d60 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
34d70 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
34d80 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 sqlite3_reset(sq
34d90 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d lite3_stmt *pStm
34da0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
34db0 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 REF: Create Or R
34dc0 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 edefine SQL Func
34dd0 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 tions.** KEYWORD
34de0 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 S: {function cre
34df0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a ation routines}.
34e00 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 ** KEYWORDS: {ap
34e10 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
34e20 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a d SQL function}.
34e30 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 ** KEYWORDS: {ap
34e40 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
34e50 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d d SQL functions}
34e60 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
34e70 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 te3.**.** ^These
34e80 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c functions (coll
34e90 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 ectively known a
34ea0 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 s "function crea
34eb0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a tion routines").
34ec0 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 ** are used to a
34ed0 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 dd SQL functions
34ee0 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f or aggregates o
34ef0 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 r to redefine th
34f00 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 e behavior.** of
34f10 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 existing SQL fu
34f20 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 nctions or aggre
34f30 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 gates. The only
34f40 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 differences bet
34f50 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f ween.** these ro
34f60 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 utines are the t
34f70 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 ext encoding exp
34f80 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 ected for.** the
34f90 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
34fa0 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 r (the name of t
34fb0 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e he function bein
34fc0 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e g created).** an
34fd0 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f d the presence o
34fe0 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64 r absence of a d
34ff0 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 estructor callba
35000 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 ck for.** the ap
35010 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 plication data p
35020 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ointer..**.** ^T
35030 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
35040 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 er is the [datab
35050 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
35060 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c to which the SQL
35070 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 .** function is
35080 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 to be added. ^I
35090 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e f an application
350a0 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 uses more than
350b0 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 one database.**
350c0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 connection then
350d0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
350e0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ned SQL function
350f0 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a s must be added.
35100 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 ** to each datab
35110 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 ase connection s
35120 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a eparately..**.**
35130 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 ^The second par
35140 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 ameter is the na
35150 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 me of the SQL fu
35160 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 nction to be cre
35170 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 ated or.** redef
35180 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 ined. ^The leng
35190 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 th of the name i
351a0 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 s limited to 255
351b0 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d bytes in a UTF-
351c0 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74 8.** representat
351d0 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f ion, exclusive o
351e0 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 f the zero-termi
351f0 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 nator. ^Note th
35200 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c at the name.** l
35210 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 ength limit is i
35220 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e n UTF-8 bytes, n
35230 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f ot characters no
35240 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20 r UTF-16 bytes.
35250 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 .** ^Any attemp
35260 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 t to create a fu
35270 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f nction with a lo
35280 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c nger name.** wil
35290 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c l result in [SQL
352a0 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e ITE_MISUSE] bein
352b0 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a g returned..**.*
352c0 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 * ^The third par
352d0 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a ameter (nArg).**
352e0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f is the number o
352f0 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 f arguments that
35300 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
35310 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 n or.** aggregat
35320 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 e takes. ^If thi
35330 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d s parameter is -
35340 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 1, then the SQL
35350 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 function or.** a
35360 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b ggregate may tak
35370 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 e any number of
35380 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 arguments betwee
35390 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 n 0 and the limi
353a0 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c t.** set by [sql
353b0 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c ite3_limit]([SQL
353c0 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 ITE_LIMIT_FUNCTI
353d0 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 ON_ARG]). If th
353e0 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d e third.** param
353f0 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 eter is less tha
35400 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 n -1 or greater
35410 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 than 127 then th
35420 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a e behavior is.**
35430 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a undefined..**.*
35440 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 * ^The fourth pa
35450 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 rameter, eTextRe
35460 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 p, specifies wha
35470 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 t.** [SQLITE_UTF
35480 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 8 | text encodin
35490 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 g] this SQL func
354a0 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 tion prefers for
354b0 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 .** its paramete
354c0 72 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 rs. The applica
354d0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74 20 tion should set
354e0 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 74 this parameter t
354f0 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 o.** [SQLITE_UTF
35500 31 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75 6e 16LE] if the fun
35510 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 ction implementa
35520 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a tion invokes .**
35530 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
35540 74 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61 text16le()] on a
35550 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c n input, or [SQL
35560 49 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66 20 ITE_UTF16BE] if
35570 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 the.** implement
35580 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 ation invokes [s
35590 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
355a0 74 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69 t16be()] on an i
355b0 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c nput, or.** [SQL
355c0 49 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b 73 ITE_UTF16] if [s
355d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
355e0 74 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 t16()] is used,
355f0 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d or [SQLITE_UTF8]
35600 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20 20 .** otherwise.
35610 5e 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 ^The same SQL fu
35620 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 nction may be re
35630 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c gistered multipl
35640 65 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a e times using.**
35650 20 64 69 66 66 65 72 65 6e 74 20 70 72 65 66 65 different prefe
35660 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 rred text encodi
35670 6e 67 73 2c 20 77 69 74 68 20 64 69 66 66 65 72 ngs, with differ
35680 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ent implementati
35690 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 ons for.** each
356a0 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 encoding..** ^Wh
356b0 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c en multiple impl
356c0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 ementations of t
356d0 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e he same function
356e0 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 are available,
356f0 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 SQLite.** will p
35700 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 ick the one that
35710 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 involves the le
35720 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 ast amount of da
35730 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a ta conversion..*
35740 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 *.** ^The fourth
35750 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 6f parameter may o
35760 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65 ptionally be ORe
35770 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 d with [SQLITE_D
35780 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a ETERMINISTIC].**
35790 20 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74 20 to signal that
357a0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c the function wil
357b0 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 l always return
357c0 74 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74 20 the same result
357d0 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d given.** the sam
357e0 65 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e 20 e inputs within
357f0 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 a single SQL sta
35800 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51 tement. Most SQ
35810 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a L functions are.
35820 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 ** deterministic
35830 2e 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e 20 . The built-in
35840 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66 [random()] SQL f
35850 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65 78 unction is an ex
35860 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75 ample of a.** fu
35870 6e 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6e nction that is n
35880 6f 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 ot deterministic
35890 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 71 75 . The SQLite qu
358a0 65 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20 61 ery planner is a
358b0 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 ble to.** perfor
358c0 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 m additional opt
358d0 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65 imizations on de
358e0 74 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e 63 terministic func
358f0 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a tions, so use.**
35900 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f of the [SQLITE_
35910 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20 66 DETERMINISTIC] f
35920 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 lag is recommend
35930 65 64 20 77 68 65 72 65 20 70 6f 73 73 69 62 6c ed where possibl
35940 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 e..**.** ^(The f
35950 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 ifth parameter i
35960 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 s an arbitrary p
35970 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 ointer. The imp
35980 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 lementation of t
35990 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 he.** function c
359a0 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 an gain access t
359b0 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 o this pointer u
359c0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 sing [sqlite3_us
359d0 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a er_data()].)^.**
359e0 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 .** ^The sixth,
359f0 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 seventh and eigh
35a00 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 th parameters, x
35a10 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 Func, xStep and
35a20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 xFinal, are.** p
35a30 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e ointers to C-lan
35a40 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 guage functions
35a50 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 that implement t
35a60 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 he SQL function
35a70 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e or.** aggregate.
35a80 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 ^A scalar SQL f
35a90 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 unction requires
35aa0 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 an implementati
35ab0 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a on of the xFunc.
35ac0 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 ** callback only
35ad0 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 ; NULL pointers
35ae0 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61 must be passed a
35af0 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 s the xStep and
35b00 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 xFinal.** parame
35b10 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 ters. ^An aggreg
35b20 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ate SQL function
35b30 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 requires an imp
35b40 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 lementation of x
35b50 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e Step.** and xFin
35b60 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e al and NULL poin
35b70 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 ter must be pass
35b80 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 ed for xFunc. ^T
35b90 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 o delete an exis
35ba0 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 ting.** SQL func
35bb0 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 tion or aggregat
35bc0 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 e, pass NULL poi
35bd0 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 nters for all th
35be0 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 ree function.**
35bf0 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a callbacks..**.**
35c00 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 ^(If the ninth
35c10 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
35c20 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
35c30 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 tion_v2() is not
35c40 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 NULL,.** then i
35c50 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 t is destructor
35c60 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 for the applicat
35c70 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 ion data pointer
35c80 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 . .** The destru
35c90 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 ctor is invoked
35ca0 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f when the functio
35cb0 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 n is deleted, ei
35cc0 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a ther by being.**
35cd0 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 overloaded or w
35ce0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 hen the database
35cf0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 connection clos
35d00 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 es.)^.** ^The de
35d10 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f structor is also
35d20 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 invoked if the
35d30 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 call to.** sqlit
35d40 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
35d50 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a on_v2() fails..*
35d60 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 * ^When the dest
35d70 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 ructor callback
35d80 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 of the tenth par
35d90 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 ameter is invoke
35da0 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 d, it.** is pass
35db0 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 ed a single argu
35dc0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 ment which is a
35dd0 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c copy of the appl
35de0 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a ication data .**
35df0 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 pointer which w
35e00 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72 as the fifth par
35e10 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
35e20 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
35e30 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 n_v2()..**.** ^I
35e40 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 t is permitted t
35e50 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 o register multi
35e60 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ple implementati
35e70 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a ons of the same.
35e80 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 ** functions wit
35e90 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 h the same name
35ea0 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20 but with either
35eb0 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 differing number
35ec0 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 s of.** argument
35ed0 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 s or differing p
35ee0 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e referred text en
35ef0 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 codings. ^SQLit
35f00 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 e will use.** th
35f10 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
35f20 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 that most close
35f30 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 ly matches the w
35f40 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a ay in which the.
35f50 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 ** SQL function
35f60 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e is used. ^A fun
35f70 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 ction implementa
35f80 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d tion with a non-
35f90 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 negative.** nArg
35fa0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 parameter is a
35fb0 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 better match tha
35fc0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 n a function imp
35fd0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 lementation with
35fe0 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e .** a negative n
35ff0 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f Arg. ^A functio
36000 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66 n where the pref
36010 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 erred text encod
36020 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 ing.** matches t
36030 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f he database enco
36040 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 ding is a better
36050 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 .** match than a
36060 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 function where
36070 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 the encoding is
36080 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 different. .**
36090 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 ^A function wher
360a0 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 e the encoding d
360b0 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 ifference is bet
360c0 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 ween UTF16le and
360d0 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 UTF16be.** is a
360e0 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 closer match th
360f0 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 an a function wh
36100 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 ere the encoding
36110 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a difference is.*
36120 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 * between UTF8 a
36130 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 nd UTF16..**.**
36140 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 ^Built-in functi
36150 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c ons may be overl
36160 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 oaded by new app
36170 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
36180 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a functions..**.*
36190 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f * ^An applicatio
361a0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
361b0 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 on is permitted
361c0 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a to call other.**
361d0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
361e0 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 es. However, su
361f0 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f ch calls must no
36200 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 t.** close the d
36210 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
36220 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 on nor finalize
36230 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65 or reset the pre
36240 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 pared.** stateme
36250 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 nt in which the
36260 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e function is runn
36270 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ing..*/.SQLITE_A
36280 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 PI int SQLITE_ST
36290 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 72 DCALL sqlite3_cr
362a0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 eate_function(.
362b0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 sqlite3 *db,.
362c0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e const char *zFun
362d0 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 ctionName,. int
362e0 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 nArg,. int eTe
362f0 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 xtRep,. void *p
36300 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 App,. void (*xF
36310 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e unc)(sqlite3_con
36320 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 text*,int,sqlite
36330 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 3_value**),. vo
36340 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 id (*xStep)(sqli
36350 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 te3_context*,int
36360 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a ,sqlite3_value**
36370 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e ),. void (*xFin
36380 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 al)(sqlite3_cont
36390 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f ext*).);.SQLITE_
363a0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 API int SQLITE_S
363b0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 TDCALL sqlite3_c
363c0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 reate_function16
363d0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c (. sqlite3 *db,
363e0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a . const void *z
363f0 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 FunctionName,.
36400 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 int nArg,. int
36410 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 eTextRep,. void
36420 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 *pApp,. void (
36430 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f *xFunc)(sqlite3_
36440 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c context*,int,sql
36450 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 ite3_value**),.
36460 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 void (*xStep)(s
36470 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
36480 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 int,sqlite3_valu
36490 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 e**),. void (*x
364a0 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 Final)(sqlite3_c
364b0 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 ontext*).);.SQLI
364c0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
364d0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
364e0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
364f0 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 n_v2(. sqlite3
36500 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 *db,. const cha
36510 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 r *zFunctionName
36520 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 ,. int nArg,.
36530 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 int eTextRep,.
36540 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f void *pApp,. vo
36550 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 id (*xFunc)(sqli
36560 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 te3_context*,int
36570 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a ,sqlite3_value**
36580 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 ),. void (*xSte
36590 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 p)(sqlite3_conte
365a0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f xt*,int,sqlite3_
365b0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 value**),. void
365c0 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 (*xFinal)(sqlit
365d0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 e3_context*),.
365e0 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 void(*xDestroy)(
365f0 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a void*).);../*.**
36600 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 CAPI3REF: Text
36610 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 Encodings.**.**
36620 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 These constant d
36630 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f efine integer co
36640 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65 des that represe
36650 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a nt the various.*
36660 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 * text encodings
36670 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 supported by SQ
36680 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 Lite..*/.#define
36690 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 SQLITE_UTF8
366a0 20 20 20 20 20 20 20 31 20 20 20 20 2f 2a 20 49 1 /* I
366b0 4d 50 3a 20 52 2d 33 37 35 31 34 2d 33 35 35 36 MP: R-37514-3556
366c0 36 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 6 */.#define SQL
366d0 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 ITE_UTF16LE
366e0 20 20 20 32 20 20 20 20 2f 2a 20 49 4d 50 3a 20 2 /* IMP:
366f0 52 2d 30 33 33 37 31 2d 33 37 36 33 37 20 2a 2f R-03371-37637 */
36700 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
36710 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33 UTF16BE 3
36720 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 35 31 /* IMP: R-51
36730 39 37 31 2d 33 34 31 35 34 20 2a 2f 0a 23 64 65 971-34154 */.#de
36740 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 fine SQLITE_UTF1
36750 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20 6 4
36760 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 /* Use native by
36770 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 te order */.#def
36780 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 ine SQLITE_ANY
36790 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 5 /
367a0 2a 20 44 65 70 72 65 63 61 74 65 64 20 2a 2f 0a * Deprecated */.
367b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 #define SQLITE_U
367c0 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 TF16_ALIGNED 8
367d0 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 /* sqlite3_cr
367e0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f eate_collation o
367f0 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 nly */../*.** CA
36800 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e PI3REF: Function
36810 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 Flags.**.** The
36820 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 se constants may
36830 20 62 65 20 4f 52 65 64 20 74 6f 67 65 74 68 65 be ORed togethe
36840 72 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b r with the .** [
36850 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 70 72 SQLITE_UTF8 | pr
36860 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 eferred text enc
36870 6f 64 69 6e 67 5d 20 61 73 20 74 68 65 20 66 6f oding] as the fo
36880 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a urth argument.**
36890 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 to [sqlite3_cre
368a0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c ate_function()],
368b0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
368c0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 20 _function16()],
368d0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 or.** [sqlite3_c
368e0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 reate_function_v
368f0 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 2()]..*/.#define
36900 20 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e SQLITE_DETERMIN
36910 49 53 54 49 43 20 20 20 20 30 78 38 30 30 0a 0a ISTIC 0x800..
36920 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
36930 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 Deprecated Funct
36940 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 ions.** DEPRECAT
36950 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 ED.**.** These f
36960 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 unctions are [de
36970 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f precated]. In o
36980 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e rder to maintain
36990 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f .** backwards co
369a0 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 mpatibility with
369b0 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 older code, the
369c0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e se functions con
369d0 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 tinue .** to be
369e0 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 supported. Howe
369f0 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 ver, new applica
36a00 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f tions should avo
36a10 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 id.** the use of
36a20 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 these functions
36a30 2e 20 20 54 6f 20 65 6e 63 6f 75 72 61 67 65 20 . To encourage
36a40 70 72 6f 67 72 61 6d 6d 65 72 73 20 74 6f 20 61 programmers to a
36a50 76 6f 69 64 0a 2a 2a 20 74 68 65 73 65 20 66 75 void.** these fu
36a60 6e 63 74 69 6f 6e 73 2c 20 77 65 20 77 69 6c 6c nctions, we will
36a70 20 6e 6f 74 20 65 78 70 6c 61 69 6e 20 77 68 61 not explain wha
36a80 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 t they do..*/.#i
36a90 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 fndef SQLITE_OMI
36aa0 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c T_DEPRECATED.SQL
36ab0 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 ITE_API SQLITE_D
36ac0 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 53 51 EPRECATED int SQ
36ad0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
36ae0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
36af0 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e ount(sqlite3_con
36b00 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 text*);.SQLITE_A
36b10 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 PI SQLITE_DEPREC
36b20 41 54 45 44 20 69 6e 74 20 53 51 4c 49 54 45 5f ATED int SQLITE_
36b30 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
36b40 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f expired(sqlite3_
36b50 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 stmt*);.SQLITE_A
36b60 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 PI SQLITE_DEPREC
36b70 41 54 45 44 20 69 6e 74 20 53 51 4c 49 54 45 5f ATED int SQLITE_
36b80 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
36b90 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 transfer_binding
36ba0 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c s(sqlite3_stmt*,
36bb0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b sqlite3_stmt*);
36bc0 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 .SQLITE_API SQLI
36bd0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e TE_DEPRECATED in
36be0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
36bf0 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f sqlite3_global_
36c00 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 recover(void);.S
36c10 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
36c20 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 _DEPRECATED void
36c30 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
36c40 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 sqlite3_thread_c
36c50 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 leanup(void);.SQ
36c60 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
36c70 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 53 DEPRECATED int S
36c80 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
36c90 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 lite3_memory_ala
36ca0 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a rm(void(*)(void*
36cb0 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 ,sqlite3_int64,i
36cc0 6e 74 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 nt),.
36cd0 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 2a void*
36ce0 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b ,sqlite3_int64);
36cf0 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 .#endif../*.** C
36d00 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 API3REF: Obtaini
36d10 6e 67 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a ng SQL Values.**
36d20 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
36d30 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 _value.**.** The
36d40 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c C-language impl
36d50 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 ementation of SQ
36d60 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 L functions and
36d70 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a aggregates uses.
36d80 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 ** this set of i
36d90 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 nterface routine
36da0 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 s to access the
36db0 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 parameter values
36dc0 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 on.** the funct
36dd0 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 ion or aggregate
36de0 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 . .**.** The xF
36df0 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 unc (for scalar
36e00 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 functions) or xS
36e10 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 tep (for aggrega
36e20 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a tes) parameters.
36e30 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ** to [sqlite3_c
36e40 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 reate_function()
36e50 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 ] and [sqlite3_c
36e60 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 reate_function16
36e70 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 ()].** define ca
36e80 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 llbacks that imp
36e90 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 lement the SQL f
36ea0 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 unctions and agg
36eb0 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 regates..** The
36ec0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 3rd parameter to
36ed0 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 these callbacks
36ee0 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 is an array of
36ef0 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b pointers to.** [
36f00 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
36f10 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 3_value] objects
36f20 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 . There is one
36f30 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 [sqlite3_value]
36f40 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 object for.** ea
36f50 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 ch parameter to
36f60 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
36f70 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 . These routine
36f80 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a s are used to.**
36f90 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 extract values
36fa0 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 from the [sqlite
36fb0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 3_value] objects
36fc0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f ..**.** These ro
36fd0 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 utines work only
36fe0 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 with [protected
36ff0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
37000 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 objects..** Any
37010 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 attempt to use t
37020 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e hese routines on
37030 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 an [unprotected
37040 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a sqlite3_value].
37050 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 ** object result
37060 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 s in undefined b
37070 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e ehavior..**.** ^
37080 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 These routines w
37090 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 ork just like th
370a0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 e corresponding
370b0 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 [column access f
370c0 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 unctions].** exc
370d0 65 70 74 20 74 68 61 74 20 74 68 65 73 65 20 72 ept that these r
370e0 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 outines take a s
370f0 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 ingle [protected
37100 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
37110 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 object.** pointe
37120 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b r instead of a [
37130 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 sqlite3_stmt*] p
37140 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e ointer and an in
37150 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d teger column num
37160 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ber..**.** ^The
37170 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
37180 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 xt16() interface
37190 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d extracts a UTF-
371a0 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 16 string.** in
371b0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d the native byte-
371c0 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 order of the hos
371d0 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 t machine. ^The
371e0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 .** sqlite3_valu
371f0 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 e_text16be() and
37200 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
37210 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 ext16le() interf
37220 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 aces.** extract
37230 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 UTF-16 strings a
37240 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 s big-endian and
37250 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 little-endian r
37260 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a espectively..**.
37270 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 ** ^(The sqlite3
37280 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 _value_numeric_t
37290 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 ype() interface
372a0 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c attempts to appl
372b0 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 y.** numeric aff
372c0 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c inity to the val
372d0 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 ue. This means
372e0 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 that an attempt
372f0 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f is.** made to co
37300 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 nvert the value
37310 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 to an integer or
37320 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e floating point.
37330 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 If.** such a c
37340 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 onversion is pos
37350 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f sible without lo
37360 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f ss of informatio
37370 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 n (in other.** w
37380 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c ords, if the val
37390 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 ue is a string t
373a0 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 hat looks like a
373b0 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e number).** then
373c0 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 the conversion
373d0 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f is performed. O
373e0 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 therwise no conv
373f0 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a ersion occurs..*
37400 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e * The [SQLITE_IN
37410 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 TEGER | datatype
37420 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 ] after conversi
37430 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 on is returned.)
37440 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 ^.**.** Please p
37450 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 ay particular at
37460 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 tention to the f
37470 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 act that the poi
37480 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a nter returned.**
37490 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 from [sqlite3_v
374a0 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 alue_blob()], [s
374b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
374c0 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c t()], or.** [sql
374d0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
374e0 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6()] can be inva
374f0 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 lidated by a sub
37500 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a sequent call to.
37510 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 ** [sqlite3_valu
37520 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c e_bytes()], [sql
37530 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 ite3_value_bytes
37540 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 16()], [sqlite3_
37550 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a value_text()],.*
37560 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 * or [sqlite3_va
37570 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a lue_text16()]..*
37580 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
37590 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c nes must be call
375a0 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 ed from the same
375b0 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 thread as.** th
375c0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 e SQL function t
375d0 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 hat supplied the
375e0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a [sqlite3_value*
375f0 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f ] parameters..*/
37600 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
37610 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 t void *SQLITE_S
37620 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 TDCALL sqlite3_v
37630 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 alue_blob(sqlite
37640 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 3_value*);.SQLIT
37650 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
37660 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
37670 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c _value_bytes(sql
37680 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 ite3_value*);.SQ
37690 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
376a0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
376b0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 te3_value_bytes1
376c0 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 6(sqlite3_value*
376d0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f );.SQLITE_API do
376e0 75 62 6c 65 20 53 51 4c 49 54 45 5f 53 54 44 43 uble SQLITE_STDC
376f0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ALL sqlite3_valu
37700 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 e_double(sqlite3
37710 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 _value*);.SQLITE
37720 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f _API int SQLITE_
37730 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
37740 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 value_int(sqlite
37750 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 3_value*);.SQLIT
37760 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e E_API sqlite3_in
37770 74 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 t64 SQLITE_STDCA
37780 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 LL sqlite3_value
37790 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 _int64(sqlite3_v
377a0 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 alue*);.SQLITE_A
377b0 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 PI const unsigne
377c0 64 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 d char *SQLITE_S
377d0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 TDCALL sqlite3_v
377e0 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 alue_text(sqlite
377f0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 3_value*);.SQLIT
37800 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 E_API const void
37810 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c *SQLITE_STDCALL
37820 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
37830 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 ext16(sqlite3_va
37840 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 lue*);.SQLITE_AP
37850 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 I const void *SQ
37860 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
37870 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
37880 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 6le(sqlite3_valu
37890 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 e*);.SQLITE_API
378a0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 const void *SQLI
378b0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
378c0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 e3_value_text16b
378d0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a e(sqlite3_value*
378e0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
378f0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
37900 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
37910 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 ype(sqlite3_valu
37920 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 e*);.SQLITE_API
37930 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 int SQLITE_STDCA
37940 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 LL sqlite3_value
37950 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 _numeric_type(sq
37960 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a lite3_value*);..
37970 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
37980 46 69 6e 64 69 6e 67 20 54 68 65 20 53 75 62 74 Finding The Subt
37990 79 70 65 20 4f 66 20 53 51 4c 20 56 61 6c 75 65 ype Of SQL Value
379a0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c s.** METHOD: sql
379b0 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a ite3_value.**.**
379c0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c The sqlite3_val
379d0 75 65 5f 73 75 62 74 79 70 65 28 56 29 20 66 75 ue_subtype(V) fu
379e0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 nction returns t
379f0 68 65 20 73 75 62 74 79 70 65 20 66 6f 72 0a 2a he subtype for.*
37a00 2a 20 61 6e 20 5b 61 70 70 6c 69 63 61 74 69 6f * an [applicatio
37a10 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 n-defined SQL fu
37a20 6e 63 74 69 6f 6e 5d 20 61 72 67 75 6d 65 6e 74 nction] argument
37a30 20 56 2e 20 20 54 68 65 20 73 75 62 74 79 70 65 V. The subtype
37a40 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 .** information
37a50 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 70 can be used to p
37a60 61 73 73 20 61 20 6c 69 6d 69 74 65 64 20 61 6d ass a limited am
37a70 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 78 74 20 ount of context
37a80 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 53 51 4c 20 from.** one SQL
37a90 66 75 6e 63 74 69 6f 6e 20 74 6f 20 61 6e 6f 74 function to anot
37aa0 68 65 72 2e 20 20 55 73 65 20 74 68 65 20 5b 73 her. Use the [s
37ab0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 73 75 qlite3_result_su
37ac0 62 74 79 70 65 28 29 5d 0a 2a 2a 20 72 6f 75 74 btype()].** rout
37ad0 69 6e 65 20 74 6f 20 73 65 74 20 74 68 65 20 73 ine to set the s
37ae0 75 62 74 79 70 65 20 66 6f 72 20 74 68 65 20 72 ubtype for the r
37af0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 61 eturn value of a
37b00 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a n SQL function..
37b10 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b **.** SQLite mak
37b20 65 73 20 6e 6f 20 75 73 65 20 6f 66 20 73 75 62 es no use of sub
37b30 74 79 70 65 20 69 74 73 65 6c 66 2e 20 20 49 74 type itself. It
37b40 20 6d 65 72 65 6c 79 20 70 61 73 73 65 73 20 74 merely passes t
37b50 68 65 20 73 75 62 74 79 70 65 0a 2a 2a 20 66 72 he subtype.** fr
37b60 6f 6d 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 om the result of
37b70 20 6f 6e 65 20 5b 61 70 70 6c 69 63 61 74 69 6f one [applicatio
37b80 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 n-defined SQL fu
37b90 6e 63 74 69 6f 6e 5d 20 69 6e 74 6f 20 74 68 65 nction] into the
37ba0 0a 2a 2a 20 69 6e 70 75 74 20 6f 66 20 61 6e 6f .** input of ano
37bb0 74 68 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f ther..*/.SQLITE_
37bc0 41 50 49 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 API unsigned int
37bd0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
37be0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 73 75 sqlite3_value_su
37bf0 62 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 btype(sqlite3_va
37c00 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 lue*);../*.** CA
37c10 50 49 33 52 45 46 3a 20 43 6f 70 79 20 41 6e 64 PI3REF: Copy And
37c20 20 46 72 65 65 20 53 51 4c 20 56 61 6c 75 65 73 Free SQL Values
37c30 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
37c40 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 te3_value.**.**
37c50 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c ^The sqlite3_val
37c60 75 65 5f 64 75 70 28 56 29 20 69 6e 74 65 72 66 ue_dup(V) interf
37c70 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 ace makes a copy
37c80 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
37c90 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 _value].** objec
37ca0 74 20 44 20 61 6e 64 20 72 65 74 75 72 6e 73 20 t D and returns
37cb0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 a pointer to tha
37cc0 74 20 63 6f 70 79 2e 20 20 5e 54 68 65 20 5b 73 t copy. ^The [s
37cd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 72 65 qlite3_value] re
37ce0 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 61 20 5b turned.** is a [
37cf0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
37d00 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 3_value] object
37d10 65 76 65 6e 20 69 66 20 74 68 65 20 69 6e 70 75 even if the inpu
37d20 74 20 69 73 20 6e 6f 74 2e 0a 2a 2a 20 5e 54 68 t is not..** ^Th
37d30 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f e sqlite3_value_
37d40 64 75 70 28 56 29 20 69 6e 74 65 72 66 61 63 65 dup(V) interface
37d50 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 returns NULL if
37d60 20 56 20 69 73 20 4e 55 4c 4c 20 6f 72 20 69 66 V is NULL or if
37d70 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c a.** memory all
37d80 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2e 0a 2a ocation fails..*
37d90 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
37da0 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 56 29 20 3_value_free(V)
37db0 69 6e 74 65 72 66 61 63 65 20 66 72 65 65 73 20 interface frees
37dc0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 an [sqlite3_valu
37dd0 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 72 65 e] object.** pre
37de0 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 viously obtained
37df0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 from [sqlite3_v
37e00 61 6c 75 65 5f 64 75 70 28 29 5d 2e 20 20 5e 49 alue_dup()]. ^I
37e10 66 20 56 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f f V is a NULL po
37e20 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6e 20 73 71 inter.** then sq
37e30 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 lite3_value_free
37e40 28 56 29 20 69 73 20 61 20 68 61 72 6d 6c 65 73 (V) is a harmles
37e50 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 s no-op..*/.SQLI
37e60 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 76 TE_API sqlite3_v
37e70 61 6c 75 65 20 2a 53 51 4c 49 54 45 5f 53 54 44 alue *SQLITE_STD
37e80 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c CALL sqlite3_val
37e90 75 65 5f 64 75 70 28 63 6f 6e 73 74 20 73 71 6c ue_dup(const sql
37ea0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 ite3_value*);.SQ
37eb0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 LITE_API void SQ
37ec0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
37ed0 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 ite3_value_free(
37ee0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
37ef0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
37f00 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 : Obtain Aggrega
37f10 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 te Function Cont
37f20 65 78 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 ext.** METHOD: s
37f30 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a qlite3_context.*
37f40 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 *.** Implementat
37f50 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74 ions of aggregat
37f60 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 e SQL functions
37f70 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 use this.** rout
37f80 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 ine to allocate
37f90 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 memory for stori
37fa0 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a ng their state..
37fb0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 **.** ^The first
37fc0 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 time the sqlite
37fd0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 3_aggregate_cont
37fe0 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 ext(C,N) routine
37ff0 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 is called .** f
38000 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 or a particular
38010 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 aggregate functi
38020 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c on, SQLite.** al
38030 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d locates N of mem
38040 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 ory, zeroes out
38050 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 that memory, and
38060 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
38070 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 er.** to the new
38080 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 memory. ^On sec
38090 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 ond and subseque
380a0 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 nt calls to.** s
380b0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
380c0 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 _context() for t
380d0 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 he same aggregat
380e0 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 e function insta
380f0 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 nce,.** the same
38100 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72 buffer is retur
38110 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 ned. Sqlite3_ag
38120 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 gregate_context(
38130 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a ) is normally.**
38140 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 called once for
38150 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e each invocation
38160 20 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 61 of the xStep ca
38170 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 llback and then
38180 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 one.** last time
38190 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c when the xFinal
381a0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
381b0 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f oked. ^(When no
381c0 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 rows match.** a
381d0 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 n aggregate quer
381e0 79 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 63 y, the xStep() c
381f0 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61 allback of the a
38200 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f ggregate functio
38210 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 n.** implementat
38220 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c ion is never cal
38230 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 led and xFinal()
38240 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74 is called exact
38250 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 ly once..** In t
38260 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69 hose cases, sqli
38270 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
38280 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 65 ntext() might be
38290 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a called for the.
382a0 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 72 ** first time fr
382b0 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c om within xFinal
382c0 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ().)^.**.** ^The
382d0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 sqlite3_aggrega
382e0 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 te_context(C,N)
382f0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
38300 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a a NULL pointer .
38310 2a 2a 20 77 68 65 6e 20 66 69 72 73 74 20 63 61 ** when first ca
38320 6c 6c 65 64 20 69 66 20 4e 20 69 73 20 6c 65 73 lled if N is les
38330 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 s than or equal
38340 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 to zero or if a
38350 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 memory.** alloca
38360 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e te error occurs.
38370 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f .**.** ^(The amo
38380 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c unt of space all
38390 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 ocated by sqlite
383a0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 3_aggregate_cont
383b0 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 ext(C,N) is.** d
383c0 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 etermined by the
383d0 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 N parameter on
383e0 66 69 72 73 74 20 73 75 63 63 65 73 73 66 75 6c first successful
383f0 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 call. Changing
38400 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 the.** value of
38410 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 N in subsequent
38420 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
38430 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 _aggregate_conte
38440 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 xt() within.** t
38450 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 he same aggregat
38460 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 e function insta
38470 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 nce will not res
38480 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a ize the memory.*
38490 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 * allocation.)^
384a0 20 57 69 74 68 69 6e 20 74 68 65 20 78 46 69 6e Within the xFin
384b0 61 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20 al callback, it
384c0 69 73 20 63 75 73 74 6f 6d 61 72 79 20 74 6f 20 is customary to
384d0 73 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 set.** N=0 in ca
384e0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 lls to sqlite3_a
384f0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
38500 28 43 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e 6f (C,N) so that no
38510 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20 6d .** pointless m
38520 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
38530 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e s occur..**.** ^
38540 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 SQLite automatic
38550 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d ally frees the m
38560 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 emory allocated
38570 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 by .** sqlite3_a
38580 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
38590 28 29 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 () when the aggr
385a0 65 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63 egate query conc
385b0 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ludes..**.** The
385c0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
385d0 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79 20 must be a copy
385e0 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 of the.** [sqlit
385f0 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c e3_context | SQL
38600 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 function contex
38610 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66 t] that is the f
38620 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a irst parameter.*
38630 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f * to the xStep o
38640 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 r xFinal callbac
38650 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 k routine that i
38660 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 mplements the ag
38670 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 gregate.** funct
38680 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 ion..**.** This
38690 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 routine must be
386a0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 called from the
386b0 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 same thread in w
386c0 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 hich.** the aggr
386d0 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 egate SQL functi
386e0 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a on is running..*
386f0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 /.SQLITE_API voi
38700 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c d *SQLITE_STDCAL
38710 4c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 L sqlite3_aggreg
38720 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 ate_context(sqli
38730 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e te3_context*, in
38740 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a t nBytes);../*.*
38750 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 * CAPI3REF: User
38760 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 Data For Functi
38770 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f