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 38 2e 31 32 2e 20 20 ersion 3.8.12.
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 49 6e 63 6c 75 64 H_../*.** Includ
0780: 65 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c e the header fil
0790: 65 20 75 73 65 64 20 74 6f 20 63 75 73 74 6f 6d e used to custom
07a0: 69 7a 65 20 74 68 65 20 63 6f 6d 70 69 6c 65 72 ize the compiler
07b0: 20 6f 70 74 69 6f 6e 73 20 66 6f 72 20 4d 53 56 options for MSV
07c0: 43 2e 0a 2a 2a 20 54 68 69 73 20 73 68 6f 75 6c C..** This shoul
07d0: 64 20 62 65 20 64 6f 6e 65 20 66 69 72 73 74 20 d be done first
07e0: 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73 so that it can s
07f0: 75 63 63 65 73 73 66 75 6c 6c 79 20 70 72 65 76 uccessfully prev
0800: 65 6e 74 20 73 70 75 72 69 6f 75 73 0a 2a 2a 20 ent spurious.**
0810: 63 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69 6e 67 compiler warning
0820: 73 20 64 75 65 20 74 6f 20 73 75 62 73 65 71 75 s due to subsequ
0830: 65 6e 74 20 63 6f 6e 74 65 6e 74 20 69 6e 20 74 ent content in t
0840: 68 69 73 20 66 69 6c 65 20 61 6e 64 20 6f 74 68 his file and oth
0850: 65 72 20 66 69 6c 65 73 0a 2a 2a 20 74 68 61 74 er files.** that
0860: 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20 62 79 are included by
0870: 20 74 68 69 73 20 66 69 6c 65 2e 0a 2a 2f 0a 2f this file..*/./
0880: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 49 ************** I
0890: 6e 63 6c 75 64 65 20 6d 73 76 63 2e 68 20 69 6e nclude msvc.h in
08a0: 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 73 the middle of s
08b0: 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a qliteInt.h *****
08c0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f *************/./
08d0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 ************** B
08e0: 65 67 69 6e 20 66 69 6c 65 20 6d 73 76 63 2e 68 egin file msvc.h
08f0: 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ***************
0900: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0910: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f *************/./
0920: 2a 0a 2a 2a 20 32 30 31 35 20 4a 61 6e 75 61 72 *.** 2015 Januar
0930: 79 20 31 32 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 y 12.**.** The a
0940: 75 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 uthor disclaims
0950: 63 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 copyright to thi
0960: 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 s source code.
0970: 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 In place of.** a
0980: 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 legal notice, h
0990: 65 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e ere is a blessin
09a0: 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 g:.**.** May
09b0: 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 you do good and
09c0: 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 not evil..**
09d0: 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 May you find for
09e0: 67 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 giveness for you
09f0: 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 rself and forgiv
0a00: 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 e others..**
0a10: 4d 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 May you share fr
0a20: 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 eely, never taki
0a30: 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 ng more than you
0a40: 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a give..**.******
0a50: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0a60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0a70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0a80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0a90: 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 ********.**.** T
0aa0: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e his file contain
0ab0: 73 20 63 6f 64 65 20 74 68 61 74 20 69 73 20 73 s code that is s
0ac0: 70 65 63 69 66 69 63 20 74 6f 20 4d 53 56 43 2e pecific to MSVC.
0ad0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 4d 53 56 .*/.#ifndef _MSV
0ae0: 43 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f 4d 53 C_H_.#define _MS
0af0: 56 43 5f 48 5f 0a 0a 23 69 66 20 64 65 66 69 6e VC_H_..#if defin
0b00: 65 64 28 5f 4d 53 43 5f 56 45 52 29 0a 23 70 72 ed(_MSC_VER).#pr
0b10: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 agma warning(dis
0b20: 61 62 6c 65 20 3a 20 34 30 35 34 29 0a 23 70 72 able : 4054).#pr
0b30: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 agma warning(dis
0b40: 61 62 6c 65 20 3a 20 34 30 35 35 29 0a 23 70 72 able : 4055).#pr
0b50: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 agma warning(dis
0b60: 61 62 6c 65 20 3a 20 34 31 30 30 29 0a 23 70 72 able : 4100).#pr
0b70: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 agma warning(dis
0b80: 61 62 6c 65 20 3a 20 34 31 32 37 29 0a 23 70 72 able : 4127).#pr
0b90: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 agma warning(dis
0ba0: 61 62 6c 65 20 3a 20 34 31 33 30 29 0a 23 70 72 able : 4130).#pr
0bb0: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 agma warning(dis
0bc0: 61 62 6c 65 20 3a 20 34 31 35 32 29 0a 23 70 72 able : 4152).#pr
0bd0: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 agma warning(dis
0be0: 61 62 6c 65 20 3a 20 34 31 38 39 29 0a 23 70 72 able : 4189).#pr
0bf0: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 agma warning(dis
0c00: 61 62 6c 65 20 3a 20 34 32 30 36 29 0a 23 70 72 able : 4206).#pr
0c10: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 agma warning(dis
0c20: 61 62 6c 65 20 3a 20 34 32 31 30 29 0a 23 70 72 able : 4210).#pr
0c30: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 agma warning(dis
0c40: 61 62 6c 65 20 3a 20 34 32 33 32 29 0a 23 70 72 able : 4232).#pr
0c50: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 agma warning(dis
0c60: 61 62 6c 65 20 3a 20 34 32 34 34 29 0a 23 70 72 able : 4244).#pr
0c70: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 agma warning(dis
0c80: 61 62 6c 65 20 3a 20 34 33 30 35 29 0a 23 70 72 able : 4305).#pr
0c90: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 agma warning(dis
0ca0: 61 62 6c 65 20 3a 20 34 33 30 36 29 0a 23 70 72 able : 4306).#pr
0cb0: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 agma warning(dis
0cc0: 61 62 6c 65 20 3a 20 34 37 30 32 29 0a 23 70 72 able : 4702).#pr
0cd0: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 agma warning(dis
0ce0: 61 62 6c 65 20 3a 20 34 37 30 36 29 0a 23 65 6e able : 4706).#en
0cf0: 64 69 66 20 2f 2a 20 64 65 66 69 6e 65 64 28 5f dif /* defined(_
0d00: 4d 53 43 5f 56 45 52 29 20 2a 2f 0a 0a 23 65 6e MSC_VER) */..#en
0d10: 64 69 66 20 2f 2a 20 5f 4d 53 56 43 5f 48 5f 20 dif /* _MSVC_H_
0d20: 2a 2f 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a */../***********
0d30: 2a 2a 2a 20 45 6e 64 20 6f 66 20 6d 73 76 63 2e *** End of msvc.
0d40: 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a h **************
0d50: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0d60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0d70: 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a **/./***********
0d80: 2a 2a 2a 20 43 6f 6e 74 69 6e 75 69 6e 67 20 77 *** Continuing w
0d90: 68 65 72 65 20 77 65 20 6c 65 66 74 20 6f 66 66 here we left off
0da0: 20 69 6e 20 73 71 6c 69 74 65 49 6e 74 2e 68 20 in sqliteInt.h
0db0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0dc0: 2a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 **/../*.** Speci
0dd0: 61 6c 20 73 65 74 75 70 20 66 6f 72 20 56 78 57 al setup for VxW
0de0: 6f 72 6b 73 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a orks.*/./*******
0df0: 2a 2a 2a 2a 2a 2a 2a 20 49 6e 63 6c 75 64 65 20 ******* Include
0e00: 76 78 77 6f 72 6b 73 2e 68 20 69 6e 20 74 68 65 vxworks.h in the
0e10: 20 6d 69 64 64 6c 65 20 6f 66 20 73 71 6c 69 74 middle of sqlit
0e20: 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a eInt.h *********
0e30: 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a ******/./*******
0e40: 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20 66 69 ******* Begin fi
0e50: 6c 65 20 76 78 77 6f 72 6b 73 2e 68 20 2a 2a 2a le vxworks.h ***
0e60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0e70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0e80: 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30 ******/./*.** 20
0e90: 31 35 2d 30 33 2d 30 32 0a 2a 2a 0a 2a 2a 20 54 15-03-02.**.** T
0ea0: 68 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 he author discla
0eb0: 69 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f ims copyright to
0ec0: 20 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 this source cod
0ed0: 65 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a e. In place of.
0ee0: 2a 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 ** a legal notic
0ef0: 65 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 e, here is a ble
0f00: 73 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 ssing:.**.**
0f10: 4d 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 May you do good
0f20: 61 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a and not evil..**
0f30: 20 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 May you find
0f40: 20 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 forgiveness for
0f50: 20 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f yourself and fo
0f60: 72 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a rgive others..**
0f70: 20 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 May you shar
0f80: 65 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 e freely, never
0f90: 74 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e taking more than
0fa0: 20 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a you give..**.**
0fb0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0fc0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0fd0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0fe0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0ff0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a ************.**.
1000: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e ** This file con
1010: 74 61 69 6e 73 20 63 6f 64 65 20 74 68 61 74 20 tains code that
1020: 69 73 20 73 70 65 63 69 66 69 63 20 74 6f 20 57 is specific to W
1030: 69 6e 64 20 52 69 76 65 72 27 73 20 56 78 57 6f ind River's VxWo
1040: 72 6b 73 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e rks.*/.#if defin
1050: 65 64 28 5f 5f 52 54 50 5f 5f 29 20 7c 7c 20 64 ed(__RTP__) || d
1060: 65 66 69 6e 65 64 28 5f 57 52 53 5f 4b 45 52 4e efined(_WRS_KERN
1070: 45 4c 29 0a 2f 2a 20 54 68 69 73 20 69 73 20 56 EL)./* This is V
1080: 78 57 6f 72 6b 73 2e 20 20 53 65 74 20 75 70 20 xWorks. Set up
1090: 74 68 69 6e 67 73 20 73 70 65 63 69 61 6c 6c 79 things specially
10a0: 20 66 6f 72 20 74 68 61 74 20 4f 53 0a 2a 2f 0a for that OS.*/.
10b0: 23 69 6e 63 6c 75 64 65 20 3c 76 78 57 6f 72 6b #include <vxWork
10c0: 73 2e 68 3e 0a 23 69 6e 63 6c 75 64 65 20 3c 70 s.h>.#include <p
10d0: 74 68 72 65 61 64 2e 68 3e 20 20 2f 2a 20 61 6d thread.h> /* am
10e0: 61 6c 67 61 6d 61 74 6f 72 3a 20 64 6f 6e 74 63 algamator: dontc
10f0: 61 63 68 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ache */.#define
1100: 4f 53 5f 56 58 57 4f 52 4b 53 20 31 0a 23 64 65 OS_VXWORKS 1.#de
1110: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 53 5f 4f fine SQLITE_OS_O
1120: 54 48 45 52 20 30 0a 23 64 65 66 69 6e 65 20 53 THER 0.#define S
1130: 51 4c 49 54 45 5f 48 4f 4d 45 47 52 4f 57 4e 5f QLITE_HOMEGROWN_
1140: 52 45 43 55 52 53 49 56 45 5f 4d 55 54 45 58 20 RECURSIVE_MUTEX
1150: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
1160: 5f 4f 4d 49 54 5f 4c 4f 41 44 5f 45 58 54 45 4e _OMIT_LOAD_EXTEN
1170: 53 49 4f 4e 20 31 0a 23 64 65 66 69 6e 65 20 53 SION 1.#define S
1180: 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4c 4f 43 QLITE_ENABLE_LOC
1190: 4b 49 4e 47 5f 53 54 59 4c 45 20 30 0a 23 64 65 KING_STYLE 0.#de
11a0: 66 69 6e 65 20 48 41 56 45 5f 55 54 49 4d 45 20 fine HAVE_UTIME
11b0: 31 0a 23 65 6c 73 65 0a 2f 2a 20 54 68 69 73 20 1.#else./* This
11c0: 69 73 20 6e 6f 74 20 56 78 57 6f 72 6b 73 2e 20 is not VxWorks.
11d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 4f 53 5f 56 58 */.#define OS_VX
11e0: 57 4f 52 4b 53 20 30 0a 23 65 6e 64 69 66 20 2f WORKS 0.#endif /
11f0: 2a 20 64 65 66 69 6e 65 64 28 5f 57 52 53 5f 4b * defined(_WRS_K
1200: 45 52 4e 45 4c 29 20 2a 2f 0a 0a 2f 2a 2a 2a 2a ERNEL) */../****
1210: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 45 6e 64 20 6f ********** End o
1220: 66 20 76 78 77 6f 72 6b 73 2e 68 20 2a 2a 2a 2a f vxworks.h ****
1230: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1240: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1250: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a *********/./****
1260: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 43 6f 6e 74 69 ********** Conti
1270: 6e 75 69 6e 67 20 77 68 65 72 65 20 77 65 20 6c nuing where we l
1280: 65 66 74 20 6f 66 66 20 69 6e 20 73 71 6c 69 74 eft off in sqlit
1290: 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a eInt.h *********
12a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 0a 2f 2a 0a 2a *********/../*.*
12b0: 2a 20 54 68 65 73 65 20 23 64 65 66 69 6e 65 73 * These #defines
12c0: 20 73 68 6f 75 6c 64 20 65 6e 61 62 6c 65 20 3e should enable >
12d0: 32 47 42 20 66 69 6c 65 20 73 75 70 70 6f 72 74 2GB file support
12e0: 20 6f 6e 20 50 4f 53 49 58 20 69 66 20 74 68 65 on POSIX if the
12f0: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f .** underlying o
1300: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 perating system
1310: 73 75 70 70 6f 72 74 73 20 69 74 2e 20 20 49 66 supports it. If
1320: 20 74 68 65 20 4f 53 20 6c 61 63 6b 73 0a 2a 2a the OS lacks.**
1330: 20 6c 61 72 67 65 20 66 69 6c 65 20 73 75 70 70 large file supp
1340: 6f 72 74 2c 20 6f 72 20 69 66 20 74 68 65 20 4f ort, or if the O
1350: 53 20 69 73 20 77 69 6e 64 6f 77 73 2c 20 74 68 S is windows, th
1360: 65 73 65 20 73 68 6f 75 6c 64 20 62 65 20 6e 6f ese should be no
1370: 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 54 69 63 6b -ops..**.** Tick
1380: 65 74 20 23 32 37 33 39 3a 20 20 54 68 65 20 5f et #2739: The _
1390: 4c 41 52 47 45 46 49 4c 45 5f 53 4f 55 52 43 45 LARGEFILE_SOURCE
13a0: 20 6d 61 63 72 6f 20 6d 75 73 74 20 61 70 70 65 macro must appe
13b0: 61 72 20 62 65 66 6f 72 65 20 61 6e 79 0a 2a 2a ar before any.**
13c0: 20 73 79 73 74 65 6d 20 23 69 6e 63 6c 75 64 65 system #include
13d0: 73 2e 20 20 48 65 6e 63 65 2c 20 74 68 69 73 20 s. Hence, this
13e0: 62 6c 6f 63 6b 20 6f 66 20 63 6f 64 65 20 6d 75 block of code mu
13f0: 73 74 20 62 65 20 74 68 65 20 76 65 72 79 20 66 st be the very f
1400: 69 72 73 74 0a 2a 2a 20 63 6f 64 65 20 69 6e 20 irst.** code in
1410: 61 6c 6c 20 73 6f 75 72 63 65 20 66 69 6c 65 73 all source files
1420: 2e 0a 2a 2a 0a 2a 2a 20 4c 61 72 67 65 20 66 69 ..**.** Large fi
1430: 6c 65 20 73 75 70 70 6f 72 74 20 63 61 6e 20 62 le support can b
1440: 65 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 e disabled using
1450: 20 74 68 65 20 2d 44 53 51 4c 49 54 45 5f 44 49 the -DSQLITE_DI
1460: 53 41 42 4c 45 5f 4c 46 53 20 73 77 69 74 63 68 SABLE_LFS switch
1470: 0a 2a 2a 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 .** on the compi
1480: 6c 65 72 20 63 6f 6d 6d 61 6e 64 20 6c 69 6e 65 ler command line
1490: 2e 20 20 54 68 69 73 20 69 73 20 6e 65 63 65 73 . This is neces
14a0: 73 61 72 79 20 69 66 20 79 6f 75 20 61 72 65 20 sary if you are
14b0: 63 6f 6d 70 69 6c 69 6e 67 0a 2a 2a 20 6f 6e 20 compiling.** on
14c0: 61 20 72 65 63 65 6e 74 20 6d 61 63 68 69 6e 65 a recent machine
14d0: 20 28 65 78 3a 20 52 65 64 20 48 61 74 20 37 2e (ex: Red Hat 7.
14e0: 32 29 20 62 75 74 20 79 6f 75 20 77 61 6e 74 20 2) but you want
14f0: 79 6f 75 72 20 63 6f 64 65 20 74 6f 20 77 6f 72 your code to wor
1500: 6b 0a 2a 2a 20 6f 6e 20 61 6e 20 6f 6c 64 65 72 k.** on an older
1510: 20 6d 61 63 68 69 6e 65 20 28 65 78 3a 20 52 65 machine (ex: Re
1520: 64 20 48 61 74 20 36 2e 30 29 2e 20 20 49 66 20 d Hat 6.0). If
1530: 79 6f 75 20 63 6f 6d 70 69 6c 65 20 6f 6e 20 52 you compile on R
1540: 65 64 20 48 61 74 20 37 2e 32 0a 2a 2a 20 77 69 ed Hat 7.2.** wi
1550: 74 68 6f 75 74 20 74 68 69 73 20 6f 70 74 69 6f thout this optio
1560: 6e 2c 20 4c 46 53 20 69 73 20 65 6e 61 62 6c 65 n, LFS is enable
1570: 2e 20 20 42 75 74 20 4c 46 53 20 64 6f 65 73 20 . But LFS does
1580: 6e 6f 74 20 65 78 69 73 74 20 69 6e 20 74 68 65 not exist in the
1590: 20 6b 65 72 6e 65 6c 0a 2a 2a 20 69 6e 20 52 65 kernel.** in Re
15a0: 64 20 48 61 74 20 36 2e 30 2c 20 73 6f 20 74 68 d Hat 6.0, so th
15b0: 65 20 63 6f 64 65 20 77 6f 6e 27 74 20 77 6f 72 e code won't wor
15c0: 6b 2e 20 20 48 65 6e 63 65 2c 20 66 6f 72 20 6d k. Hence, for m
15d0: 61 78 69 6d 75 6d 20 62 69 6e 61 72 79 0a 2a 2a aximum binary.**
15e0: 20 70 6f 72 74 61 62 69 6c 69 74 79 20 79 6f 75 portability you
15f0: 20 73 68 6f 75 6c 64 20 6f 6d 69 74 20 4c 46 53 should omit LFS
1600: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 76 ..**.** The prev
1610: 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 20 77 ious paragraph w
1620: 61 73 20 77 72 69 74 74 65 6e 20 69 6e 20 32 30 as written in 20
1630: 30 35 2e 20 20 28 54 68 69 73 20 70 61 72 61 67 05. (This parag
1640: 72 61 70 68 20 69 73 20 77 72 69 74 74 65 6e 0a raph is written.
1650: 2a 2a 20 6f 6e 20 32 30 30 38 2d 31 31 2d 32 38 ** on 2008-11-28
1660: 2e 29 20 54 68 65 73 65 20 64 61 79 73 2c 20 61 .) These days, a
1670: 6c 6c 20 4c 69 6e 75 78 20 6b 65 72 6e 65 6c 73 ll Linux kernels
1680: 20 73 75 70 70 6f 72 74 20 6c 61 72 67 65 20 66 support large f
1690: 69 6c 65 73 2c 20 73 6f 0a 2a 2a 20 79 6f 75 20 iles, so.** you
16a0: 73 68 6f 75 6c 64 20 70 72 6f 62 61 62 6c 79 20 should probably
16b0: 6c 65 61 76 65 20 4c 46 53 20 65 6e 61 62 6c 65 leave LFS enable
16c0: 64 2e 20 20 42 75 74 20 73 6f 6d 65 20 65 6d 62 d. But some emb
16d0: 65 64 64 65 64 20 70 6c 61 74 66 6f 72 6d 73 20 edded platforms
16e0: 6d 69 67 68 74 0a 2a 2a 20 6c 61 63 6b 20 4c 46 might.** lack LF
16f0: 53 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 S in which case
1700: 74 68 65 20 53 51 4c 49 54 45 5f 44 49 53 41 42 the SQLITE_DISAB
1710: 4c 45 5f 4c 46 53 20 6d 61 63 72 6f 20 6d 69 67 LE_LFS macro mig
1720: 68 74 20 73 74 69 6c 6c 20 62 65 20 75 73 65 66 ht still be usef
1730: 75 6c 2e 0a 2a 2a 0a 2a 2a 20 53 69 6d 69 6c 61 ul..**.** Simila
1740: 72 20 69 73 20 74 72 75 65 20 66 6f 72 20 4d 61 r is true for Ma
1750: 63 20 4f 53 20 58 2e 20 20 4c 46 53 20 69 73 20 c OS X. LFS is
1760: 6f 6e 6c 79 20 73 75 70 70 6f 72 74 65 64 20 6f only supported o
1770: 6e 20 4d 61 63 20 4f 53 20 58 20 39 20 61 6e 64 n Mac OS X 9 and
1780: 20 6c 61 74 65 72 2e 0a 2a 2f 0a 23 69 66 6e 64 later..*/.#ifnd
1790: 65 66 20 53 51 4c 49 54 45 5f 44 49 53 41 42 4c ef SQLITE_DISABL
17a0: 45 5f 4c 46 53 0a 23 20 64 65 66 69 6e 65 20 5f E_LFS.# define _
17b0: 4c 41 52 47 45 5f 46 49 4c 45 20 20 20 20 20 20 LARGE_FILE
17c0: 20 31 0a 23 20 69 66 6e 64 65 66 20 5f 46 49 4c 1.# ifndef _FIL
17d0: 45 5f 4f 46 46 53 45 54 5f 42 49 54 53 0a 23 20 E_OFFSET_BITS.#
17e0: 20 20 64 65 66 69 6e 65 20 5f 46 49 4c 45 5f 4f define _FILE_O
17f0: 46 46 53 45 54 5f 42 49 54 53 20 36 34 0a 23 20 FFSET_BITS 64.#
1800: 65 6e 64 69 66 0a 23 20 64 65 66 69 6e 65 20 5f endif.# define _
1810: 4c 41 52 47 45 46 49 4c 45 5f 53 4f 55 52 43 45 LARGEFILE_SOURCE
1820: 20 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a 20 57 68 1.#endif../* Wh
1830: 61 74 20 76 65 72 73 69 6f 6e 20 6f 66 20 47 43 at version of GC
1840: 43 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 2e C is being used.
1850: 20 20 30 20 6d 65 61 6e 73 20 47 43 43 20 69 73 0 means GCC is
1860: 20 6e 6f 74 20 62 65 69 6e 67 20 75 73 65 64 20 not being used
1870: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 47 4e 55 43 */.#ifdef __GNUC
1880: 5f 5f 0a 23 20 64 65 66 69 6e 65 20 47 43 43 5f __.# define GCC_
1890: 56 45 52 53 49 4f 4e 20 28 5f 5f 47 4e 55 43 5f VERSION (__GNUC_
18a0: 5f 2a 31 30 30 30 30 30 30 2b 5f 5f 47 4e 55 43 _*1000000+__GNUC
18b0: 5f 4d 49 4e 4f 52 5f 5f 2a 31 30 30 30 2b 5f 5f _MINOR__*1000+__
18c0: 47 4e 55 43 5f 50 41 54 43 48 4c 45 56 45 4c 5f GNUC_PATCHLEVEL_
18d0: 5f 29 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e _).#else.# defin
18e0: 65 20 47 43 43 5f 56 45 52 53 49 4f 4e 20 30 0a e GCC_VERSION 0.
18f0: 23 65 6e 64 69 66 0a 0a 2f 2a 20 4e 65 65 64 65 #endif../* Neede
1900: 64 20 66 6f 72 20 76 61 72 69 6f 75 73 20 64 65 d for various de
1910: 66 69 6e 69 74 69 6f 6e 73 2e 2e 2e 20 2a 2f 0a finitions... */.
1920: 23 69 66 20 64 65 66 69 6e 65 64 28 5f 5f 47 4e #if defined(__GN
1930: 55 43 5f 5f 29 20 26 26 20 21 64 65 66 69 6e 65 UC__) && !define
1940: 64 28 5f 47 4e 55 5f 53 4f 55 52 43 45 29 0a 23 d(_GNU_SOURCE).#
1950: 20 64 65 66 69 6e 65 20 5f 47 4e 55 5f 53 4f 55 define _GNU_SOU
1960: 52 43 45 0a 23 65 6e 64 69 66 0a 0a 23 69 66 20 RCE.#endif..#if
1970: 64 65 66 69 6e 65 64 28 5f 5f 4f 70 65 6e 42 53 defined(__OpenBS
1980: 44 5f 5f 29 20 26 26 20 21 64 65 66 69 6e 65 64 D__) && !defined
1990: 28 5f 42 53 44 5f 53 4f 55 52 43 45 29 0a 23 20 (_BSD_SOURCE).#
19a0: 64 65 66 69 6e 65 20 5f 42 53 44 5f 53 4f 55 52 define _BSD_SOUR
19b0: 43 45 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a CE.#endif../*.**
19c0: 20 46 6f 72 20 4d 69 6e 47 57 2c 20 63 68 65 63 For MinGW, chec
19d0: 6b 20 74 6f 20 73 65 65 20 69 66 20 77 65 20 63 k to see if we c
19e0: 61 6e 20 69 6e 63 6c 75 64 65 20 74 68 65 20 68 an include the h
19f0: 65 61 64 65 72 20 66 69 6c 65 20 63 6f 6e 74 61 eader file conta
1a00: 69 6e 69 6e 67 20 69 74 73 0a 2a 2a 20 76 65 72 ining its.** ver
1a10: 73 69 6f 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e sion information
1a20: 2c 20 61 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 , among other th
1a30: 69 6e 67 73 2e 20 20 4e 6f 72 6d 61 6c 6c 79 2c ings. Normally,
1a40: 20 74 68 69 73 20 69 6e 74 65 72 6e 61 6c 20 4d this internal M
1a50: 69 6e 47 57 0a 2a 2a 20 68 65 61 64 65 72 20 66 inGW.** header f
1a60: 69 6c 65 20 77 6f 75 6c 64 20 5b 6f 6e 6c 79 5d ile would [only]
1a70: 20 62 65 20 69 6e 63 6c 75 64 65 64 20 61 75 74 be included aut
1a80: 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 6f 74 omatically by ot
1a90: 68 65 72 20 4d 69 6e 47 57 20 68 65 61 64 65 72 her MinGW header
1aa0: 0a 2a 2a 20 66 69 6c 65 73 3b 20 68 6f 77 65 76 .** files; howev
1ab0: 65 72 2c 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 er, the containe
1ac0: 64 20 76 65 72 73 69 6f 6e 20 69 6e 66 6f 72 6d d version inform
1ad0: 61 74 69 6f 6e 20 69 73 20 6e 6f 77 20 72 65 71 ation is now req
1ae0: 75 69 72 65 64 20 62 79 20 74 68 69 73 0a 2a 2a uired by this.**
1af0: 20 68 65 61 64 65 72 20 66 69 6c 65 20 74 6f 20 header file to
1b00: 77 6f 72 6b 20 61 72 6f 75 6e 64 20 62 69 6e 61 work around bina
1b10: 72 79 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 ry compatibility
1b20: 20 69 73 73 75 65 73 20 28 73 65 65 20 62 65 6c issues (see bel
1b30: 6f 77 29 20 61 6e 64 0a 2a 2a 20 74 68 69 73 20 ow) and.** this
1b40: 69 73 20 74 68 65 20 6f 6e 6c 79 20 6b 6e 6f 77 is the only know
1b50: 6e 20 77 61 79 20 74 6f 20 72 65 6c 69 61 62 6c n way to reliabl
1b60: 79 20 6f 62 74 61 69 6e 20 69 74 2e 20 20 54 68 y obtain it. Th
1b70: 69 73 20 65 6e 74 69 72 65 20 23 69 66 20 62 6c is entire #if bl
1b80: 6f 63 6b 0a 2a 2a 20 77 6f 75 6c 64 20 62 65 20 ock.** would be
1b90: 63 6f 6d 70 6c 65 74 65 6c 79 20 75 6e 6e 65 63 completely unnec
1ba0: 65 73 73 61 72 79 20 69 66 20 74 68 65 72 65 20 essary if there
1bb0: 77 61 73 20 61 6e 79 20 6f 74 68 65 72 20 77 61 was any other wa
1bc0: 79 20 6f 66 20 64 65 74 65 63 74 69 6e 67 0a 2a y of detecting.*
1bd0: 2a 20 4d 69 6e 47 57 20 76 69 61 20 74 68 65 69 * MinGW via thei
1be0: 72 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 28 r preprocessor (
1bf0: 65 2e 67 2e 20 69 66 20 74 68 65 79 20 63 75 73 e.g. if they cus
1c00: 74 6f 6d 69 7a 65 64 20 74 68 65 69 72 20 47 43 tomized their GC
1c10: 43 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 73 C to define.** s
1c20: 6f 6d 65 20 4d 69 6e 47 57 2d 73 70 65 63 69 66 ome MinGW-specif
1c30: 69 63 20 6d 61 63 72 6f 73 29 2e 20 20 57 68 65 ic macros). Whe
1c40: 6e 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 n compiling for
1c50: 4d 69 6e 47 57 2c 20 65 69 74 68 65 72 20 74 68 MinGW, either th
1c60: 65 0a 2a 2a 20 5f 48 41 56 45 5f 4d 49 4e 47 57 e.** _HAVE_MINGW
1c70: 5f 48 20 6f 72 20 5f 48 41 56 45 5f 5f 4d 49 4e _H or _HAVE__MIN
1c80: 47 57 5f 48 20 28 6e 6f 74 65 20 74 68 65 20 65 GW_H (note the e
1c90: 78 74 72 61 20 75 6e 64 65 72 73 63 6f 72 65 29 xtra underscore)
1ca0: 20 6d 61 63 72 6f 20 6d 75 73 74 20 62 65 0a 2a macro must be.*
1cb0: 2a 20 64 65 66 69 6e 65 64 3b 20 6f 74 68 65 72 * defined; other
1cc0: 77 69 73 65 2c 20 64 65 74 65 63 74 69 6f 6e 20 wise, detection
1cd0: 6f 66 20 63 6f 6e 64 69 74 69 6f 6e 73 20 73 70 of conditions sp
1ce0: 65 63 69 66 69 63 20 74 6f 20 4d 69 6e 47 57 20 ecific to MinGW
1cf0: 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 69 73 61 62 will be.** disab
1d00: 6c 65 64 2e 0a 2a 2f 0a 23 69 66 20 64 65 66 69 led..*/.#if defi
1d10: 6e 65 64 28 5f 48 41 56 45 5f 4d 49 4e 47 57 5f ned(_HAVE_MINGW_
1d20: 48 29 0a 23 20 69 6e 63 6c 75 64 65 20 22 6d 69 H).# include "mi
1d30: 6e 67 77 2e 68 22 0a 23 65 6c 69 66 20 64 65 66 ngw.h".#elif def
1d40: 69 6e 65 64 28 5f 48 41 56 45 5f 5f 4d 49 4e 47 ined(_HAVE__MING
1d50: 57 5f 48 29 0a 23 20 69 6e 63 6c 75 64 65 20 22 W_H).# include "
1d60: 5f 6d 69 6e 67 77 2e 68 22 0a 23 65 6e 64 69 66 _mingw.h".#endif
1d70: 0a 0a 2f 2a 0a 2a 2a 20 46 6f 72 20 4d 69 6e 47 ../*.** For MinG
1d80: 57 20 76 65 72 73 69 6f 6e 20 34 2e 78 20 28 61 W version 4.x (a
1d90: 6e 64 20 68 69 67 68 65 72 29 2c 20 63 68 65 63 nd higher), chec
1da0: 6b 20 74 6f 20 73 65 65 20 69 66 20 74 68 65 20 k to see if the
1db0: 5f 55 53 45 5f 33 32 42 49 54 5f 54 49 4d 45 5f _USE_32BIT_TIME_
1dc0: 54 0a 2a 2a 20 64 65 66 69 6e 65 20 69 73 20 72 T.** define is r
1dd0: 65 71 75 69 72 65 64 20 74 6f 20 6d 61 69 6e 74 equired to maint
1de0: 61 69 6e 20 62 69 6e 61 72 79 20 63 6f 6d 70 61 ain binary compa
1df0: 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 74 68 tibility with th
1e00: 65 20 4d 53 56 43 20 72 75 6e 74 69 6d 65 0a 2a e MSVC runtime.*
1e10: 2a 20 6c 69 62 72 61 72 79 20 69 6e 20 75 73 65 * library in use
1e20: 20 28 65 2e 67 2e 20 66 6f 72 20 57 69 6e 64 6f (e.g. for Windo
1e30: 77 73 20 58 50 29 2e 0a 2a 2f 0a 23 69 66 20 21 ws XP)..*/.#if !
1e40: 64 65 66 69 6e 65 64 28 5f 55 53 45 5f 33 32 42 defined(_USE_32B
1e50: 49 54 5f 54 49 4d 45 5f 54 29 20 26 26 20 21 64 IT_TIME_T) && !d
1e60: 65 66 69 6e 65 64 28 5f 55 53 45 5f 36 34 42 49 efined(_USE_64BI
1e70: 54 5f 54 49 4d 45 5f 54 29 20 26 26 20 5c 0a 20 T_TIME_T) && \.
1e80: 20 20 20 64 65 66 69 6e 65 64 28 5f 57 49 4e 33 defined(_WIN3
1e90: 32 29 20 26 26 20 21 64 65 66 69 6e 65 64 28 5f 2) && !defined(_
1ea0: 57 49 4e 36 34 29 20 26 26 20 5c 0a 20 20 20 20 WIN64) && \.
1eb0: 64 65 66 69 6e 65 64 28 5f 5f 4d 49 4e 47 57 5f defined(__MINGW_
1ec0: 4d 41 4a 4f 52 5f 56 45 52 53 49 4f 4e 29 20 26 MAJOR_VERSION) &
1ed0: 26 20 5f 5f 4d 49 4e 47 57 5f 4d 41 4a 4f 52 5f & __MINGW_MAJOR_
1ee0: 56 45 52 53 49 4f 4e 20 3e 3d 20 34 20 26 26 20 VERSION >= 4 &&
1ef0: 5c 0a 20 20 20 20 64 65 66 69 6e 65 64 28 5f 5f \. defined(__
1f00: 4d 53 56 43 52 54 5f 5f 29 0a 23 20 64 65 66 69 MSVCRT__).# defi
1f10: 6e 65 20 5f 55 53 45 5f 33 32 42 49 54 5f 54 49 ne _USE_32BIT_TI
1f20: 4d 45 5f 54 0a 23 65 6e 64 69 66 0a 0a 2f 2a 20 ME_T.#endif../*
1f30: 54 68 65 20 70 75 62 6c 69 63 20 53 51 4c 69 74 The public SQLit
1f40: 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 e interface. Th
1f50: 65 20 5f 46 49 4c 45 5f 4f 46 46 53 45 54 5f 42 e _FILE_OFFSET_B
1f60: 49 54 53 20 6d 61 63 72 6f 20 6d 75 73 74 20 61 ITS macro must a
1f70: 70 70 65 61 72 0a 2a 2a 20 66 69 72 73 74 20 69 ppear.** first i
1f80: 6e 20 51 4e 58 2e 20 20 41 6c 73 6f 2c 20 74 68 n QNX. Also, th
1f90: 65 20 5f 55 53 45 5f 33 32 42 49 54 5f 54 49 4d e _USE_32BIT_TIM
1fa0: 45 5f 54 20 6d 61 63 72 6f 20 6d 75 73 74 20 61 E_T macro must a
1fb0: 70 70 65 61 72 20 66 69 72 73 74 20 66 6f 72 0a ppear first for.
1fc0: 2a 2a 20 4d 69 6e 47 57 2e 0a 2a 2f 0a 2f 2a 2a ** MinGW..*/./**
1fd0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 49 6e 63 ************ Inc
1fe0: 6c 75 64 65 20 73 71 6c 69 74 65 33 2e 68 20 69 lude sqlite3.h i
1ff0: 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 n the middle of
2000: 73 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a sqliteInt.h ****
2010: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a ***********/./**
2020: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 ************ Beg
2030: 69 6e 20 66 69 6c 65 20 73 71 6c 69 74 65 33 2e in file sqlite3.
2040: 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a h **************
2050: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
2060: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a ***********/./*.
2070: 2a 2a 20 32 30 30 31 20 53 65 70 74 65 6d 62 65 ** 2001 Septembe
2080: 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 r 15.**.** The a
2090: 75 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 uthor disclaims
20a0: 63 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 copyright to thi
20b0: 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 s source code.
20c0: 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 In place of.** a
20d0: 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 legal notice, h
20e0: 65 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e ere is a blessin
20f0: 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 g:.**.** May
2100: 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 you do good and
2110: 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 not evil..**
2120: 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 May you find for
2130: 67 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 giveness for you
2140: 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 rself and forgiv
2150: 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 e others..**
2160: 4d 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 May you share fr
2170: 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 eely, never taki
2180: 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 ng more than you
2190: 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a give..**.******
21a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
21b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
21c0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
21d0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
21e0: 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68 65 61 64 ***.** This head
21f0: 65 72 20 66 69 6c 65 20 64 65 66 69 6e 65 73 20 er file defines
2200: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 68 the interface th
2210: 61 74 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 at the SQLite li
2220: 62 72 61 72 79 0a 2a 2a 20 70 72 65 73 65 6e 74 brary.** present
2230: 73 20 74 6f 20 63 6c 69 65 6e 74 20 70 72 6f 67 s to client prog
2240: 72 61 6d 73 2e 20 20 49 66 20 61 20 43 2d 66 75 rams. If a C-fu
2250: 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63 74 75 72 nction, structur
2260: 65 2c 20 64 61 74 61 74 79 70 65 2c 0a 2a 2a 20 e, datatype,.**
2270: 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 or constant defi
2280: 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 nition does not
2290: 61 70 70 65 61 72 20 69 6e 20 74 68 69 73 20 66 appear in this f
22a0: 69 6c 65 2c 20 74 68 65 6e 20 69 74 20 69 73 0a ile, then it is.
22b0: 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c 69 73 68 ** not a publish
22c0: 65 64 20 41 50 49 20 6f 66 20 53 51 4c 69 74 65 ed API of SQLite
22d0: 2c 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20 , is subject to
22e0: 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74 0a 2a change without.*
22f0: 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64 20 73 68 * notice, and sh
2300: 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72 65 66 65 ould not be refe
2310: 72 65 6e 63 65 64 20 62 79 20 70 72 6f 67 72 61 renced by progra
2320: 6d 73 20 74 68 61 74 20 75 73 65 20 53 51 4c 69 ms that use SQLi
2330: 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f te..**.** Some o
2340: 66 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e f the definition
2350: 73 20 74 68 61 74 20 61 72 65 20 69 6e 20 74 68 s that are in th
2360: 69 73 20 66 69 6c 65 20 61 72 65 20 6d 61 72 6b is file are mark
2370: 65 64 20 61 73 0a 2a 2a 20 22 65 78 70 65 72 69 ed as.** "experi
2380: 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70 65 72 69 mental". Experi
2390: 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 mental interface
23a0: 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e s are normally n
23b0: 65 77 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 72 ew.** features r
23c0: 65 63 65 6e 74 6c 79 20 61 64 64 65 64 20 74 6f ecently added to
23d0: 20 53 51 4c 69 74 65 2e 20 20 57 65 20 64 6f 20 SQLite. We do
23e0: 6e 6f 74 20 61 6e 74 69 63 69 70 61 74 65 20 63 not anticipate c
23f0: 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 65 78 70 hanges.** to exp
2400: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 erimental interf
2410: 61 63 65 73 20 62 75 74 20 72 65 73 65 72 76 65 aces but reserve
2420: 20 74 68 65 20 72 69 67 68 74 20 74 6f 20 6d 61 the right to ma
2430: 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 ke minor changes
2440: 0a 2a 2a 20 69 66 20 65 78 70 65 72 69 65 6e 63 .** if experienc
2450: 65 20 66 72 6f 6d 20 75 73 65 20 22 69 6e 20 74 e from use "in t
2460: 68 65 20 77 69 6c 64 22 20 73 75 67 67 65 73 74 he wild" suggest
2470: 20 73 75 63 68 20 63 68 61 6e 67 65 73 20 61 72 such changes ar
2480: 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a e prudent..**.**
2490: 20 54 68 65 20 6f 66 66 69 63 69 61 6c 20 43 2d The official C-
24a0: 6c 61 6e 67 75 61 67 65 20 41 50 49 20 64 6f 63 language API doc
24b0: 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 53 umentation for S
24c0: 51 4c 69 74 65 20 69 73 20 64 65 72 69 76 65 64 QLite is derived
24d0: 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 .** from comment
24e0: 73 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2e 20 s in this file.
24f0: 20 54 68 69 73 20 66 69 6c 65 20 69 73 20 74 68 This file is th
2500: 65 20 61 75 74 68 6f 72 69 74 61 74 69 76 65 20 e authoritative
2510: 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 source.** on how
2520: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
2530: 65 73 20 61 72 65 20 73 75 70 70 6f 73 65 64 20 es are supposed
2540: 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a to operate..**.*
2550: 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 * The name of th
2560: 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20 63 6f is file under co
2570: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 nfiguration mana
2580: 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c 69 74 gement is "sqlit
2590: 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68 65 20 e.h.in"..** The
25a0: 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73 20 73 makefile makes s
25b0: 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e 67 65 ome minor change
25c0: 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65 20 28 s to this file (
25d0: 73 75 63 68 20 61 73 20 69 6e 73 65 72 74 69 6e such as insertin
25e0: 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69 6f 6e g.** the version
25f0: 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63 68 61 number) and cha
2600: 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20 74 6f nges its name to
2610: 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61 73 0a "sqlite3.h" as.
2620: 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65 20 62 ** part of the b
2630: 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a 2a 2f uild process..*/
2640: 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49 54 45 .#ifndef _SQLITE
2650: 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f 53 51 3_H_.#define _SQ
2660: 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c 75 64 LITE3_H_.#includ
2670: 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20 20 20 e <stdarg.h>
2680: 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 74 /* Needed for t
2690: 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66 he definition of
26a0: 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a va_list */../*.
26b0: 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77 65 20 ** Make sure we
26c0: 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20 73 74 can call this st
26d0: 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f uff from C++..*/
26e0: 0a 23 69 66 20 30 0a 65 78 74 65 72 6e 20 22 43 .#if 0.extern "C
26f0: 22 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a " {.#endif.../*.
2700: 2a 2a 20 50 72 6f 76 69 64 65 20 74 68 65 20 61 ** Provide the a
2710: 62 69 6c 69 74 79 20 74 6f 20 6f 76 65 72 72 69 bility to overri
2720: 64 65 20 6c 69 6e 6b 61 67 65 20 66 65 61 74 75 de linkage featu
2730: 72 65 73 20 6f 66 20 74 68 65 20 69 6e 74 65 72 res of the inter
2740: 66 61 63 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 face..*/.#ifndef
2750: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a 23 SQLITE_EXTERN.#
2760: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 define SQLITE_E
2770: 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 6e XTERN extern.#en
2780: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 dif.#ifndef SQLI
2790: 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e 65 20 TE_API.# define
27a0: 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e 64 69 SQLITE_API.#endi
27b0: 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 f.#ifndef SQLITE
27c0: 5f 43 44 45 43 4c 0a 23 20 64 65 66 69 6e 65 20 _CDECL.# define
27d0: 53 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 65 6e SQLITE_CDECL.#en
27e0: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 dif.#ifndef SQLI
27f0: 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64 65 66 TE_STDCALL.# def
2800: 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44 43 41 ine SQLITE_STDCA
2810: 4c 4c 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a LL.#endif../*.**
2820: 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63 These no-op mac
2830: 72 6f 73 20 61 72 65 20 75 73 65 64 20 69 6e 20 ros are used in
2840: 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65 72 66 61 front of interfa
2850: 63 65 73 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73 ces to mark thos
2860: 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 e.** interfaces
2870: 61 73 20 65 69 74 68 65 72 20 64 65 70 72 65 63 as either deprec
2880: 61 74 65 64 20 6f 72 20 65 78 70 65 72 69 6d 65 ated or experime
2890: 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69 ntal. New appli
28a0: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c cations.** shoul
28b0: 64 20 6e 6f 74 20 75 73 65 20 64 65 70 72 65 63 d not use deprec
28c0: 61 74 65 64 20 69 6e 74 65 72 66 61 63 65 73 20 ated interfaces
28d0: 2d 20 74 68 65 79 20 61 72 65 20 73 75 70 70 6f - they are suppo
28e0: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 rted for backwar
28f0: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c ds.** compatibil
2900: 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 ity only. Appli
2910: 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73 cation writers s
2920: 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74 hould be aware t
2930: 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e hat.** experimen
2940: 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 tal interfaces a
2950: 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 re subject to ch
2960: 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65 ange in point re
2970: 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 leases..**.** Th
2980: 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20 ese macros used
2990: 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61 to resolve to va
29a0: 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63 rious kinds of c
29b0: 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68 ompiler magic th
29c0: 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65 at.** would gene
29d0: 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73 rate warning mes
29e0: 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20 sages when they
29f0: 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20 were used. But
2a00: 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 that.** compiler
2a10: 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20 magic ended up
2a20: 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20 generating such
2a30: 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20 a flurry of bug
2a40: 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20 reports.** that
2a50: 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74 we have taken it
2a60: 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e all out and gon
2a70: 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20 e back to using
2a80: 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d simple.** noop m
2a90: 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e acros..*/.#defin
2aa0: 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 e SQLITE_DEPRECA
2ab0: 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 TED.#define SQLI
2ac0: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a TE_EXPERIMENTAL.
2ad0: 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 ./*.** Ensure th
2ae0: 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 ese symbols were
2af0: 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20 not defined by
2b00: 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65 some previous he
2b10: 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 ader file..*/.#i
2b20: 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 fdef SQLITE_VERS
2b30: 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 ION.# undef SQLI
2b40: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 TE_VERSION.#endi
2b50: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f f.#ifdef SQLITE_
2b60: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 VERSION_NUMBER.#
2b70: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 undef SQLITE_VE
2b80: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e RSION_NUMBER.#en
2b90: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 dif../*.** CAPI3
2ba0: 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d REF: Compile-Tim
2bb0: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f e Library Versio
2bc0: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20 n Numbers.**.**
2bd0: 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 ^(The [SQLITE_VE
2be0: 52 53 49 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63 RSION] C preproc
2bf0: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74 essor macro in t
2c00: 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61 he sqlite3.h hea
2c10: 64 65 72 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73 der.** evaluates
2c20: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 to a string lit
2c30: 65 72 61 6c 20 74 68 61 74 20 69 73 20 74 68 65 eral that is the
2c40: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
2c50: 69 6e 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74 in the.** format
2c60: 20 22 58 2e 59 2e 5a 22 20 77 68 65 72 65 20 58 "X.Y.Z" where X
2c70: 20 69 73 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 is the major ve
2c80: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c rsion number (al
2c90: 77 61 79 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51 ways 3 for.** SQ
2ca0: 4c 69 74 65 33 29 20 61 6e 64 20 59 20 69 73 20 Lite3) and Y is
2cb0: 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f the minor versio
2cc0: 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a 20 69 n number and Z i
2cd0: 73 20 74 68 65 20 72 65 6c 65 61 73 65 20 6e 75 s the release nu
2ce0: 6d 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 mber.)^.** ^(The
2cf0: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e [SQLITE_VERSION
2d00: 5f 4e 55 4d 42 45 52 5d 20 43 20 70 72 65 70 72 _NUMBER] C prepr
2d10: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 72 65 ocessor macro re
2d20: 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69 6e 74 solves to an int
2d30: 65 67 65 72 0a 2a 2a 20 77 69 74 68 20 74 68 65 eger.** with the
2d40: 20 76 61 6c 75 65 20 28 58 2a 31 30 30 30 30 30 value (X*100000
2d50: 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 20 0 + Y*1000 + Z)
2d60: 77 68 65 72 65 20 58 2c 20 59 2c 20 61 6e 64 20 where X, Y, and
2d70: 5a 20 61 72 65 20 74 68 65 20 73 61 6d 65 0a 2a Z are the same.*
2d80: 2a 20 6e 75 6d 62 65 72 73 20 75 73 65 64 20 69 * numbers used i
2d90: 6e 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f n [SQLITE_VERSIO
2da0: 4e 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c N].)^.** The SQL
2db0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 ITE_VERSION_NUMB
2dc0: 45 52 20 66 6f 72 20 61 6e 79 20 67 69 76 65 6e ER for any given
2dd0: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 release of SQLi
2de0: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 te will also.**
2df0: 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 be larger than t
2e00: 68 65 20 72 65 6c 65 61 73 65 20 66 72 6f 6d 20 he release from
2e10: 77 68 69 63 68 20 69 74 20 69 73 20 64 65 72 69 which it is deri
2e20: 76 65 64 2e 20 20 45 69 74 68 65 72 20 59 20 77 ved. Either Y w
2e30: 69 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63 ill.** be held c
2e40: 6f 6e 73 74 61 6e 74 20 61 6e 64 20 5a 20 77 69 onstant and Z wi
2e50: 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 ll be incremente
2e60: 64 20 6f 72 20 65 6c 73 65 20 59 20 77 69 6c 6c d or else Y will
2e70: 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a be incremented.
2e80: 2a 2a 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 ** and Z will be
2e90: 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a reset to zero..
2ea0: 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20 76 65 72 73 **.** Since vers
2eb0: 69 6f 6e 20 33 2e 36 2e 31 38 2c 20 53 51 4c 69 ion 3.6.18, SQLi
2ec0: 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 te source code h
2ed0: 61 73 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 as been stored i
2ee0: 6e 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 n the.** <a href
2ef0: 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 ="http://www.fos
2f00: 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f sil-scm.org/">Fo
2f10: 73 73 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 ssil configurati
2f20: 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a on management.**
2f30: 20 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 system</a>. ^T
2f40: 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 he SQLITE_SOURCE
2f50: 5f 49 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 _ID macro evalua
2f60: 74 65 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 tes to.** a stri
2f70: 6e 67 20 77 68 69 63 68 20 69 64 65 6e 74 69 66 ng which identif
2f80: 69 65 73 20 61 20 70 61 72 74 69 63 75 6c 61 72 ies a particular
2f90: 20 63 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c check-in of SQL
2fa0: 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 ite.** within it
2fb0: 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 s configuration
2fc0: 6d 61 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65 management syste
2fd0: 6d 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f m. ^The SQLITE_
2fe0: 53 4f 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 SOURCE_ID.** str
2ff0: 69 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 ing contains the
3000: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f date and time o
3010: 66 20 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 f the check-in (
3020: 55 54 43 29 20 61 6e 64 20 61 6e 20 53 48 41 31 UTC) and an SHA1
3030: 0a 2a 2a 20 68 61 73 68 20 6f 66 20 74 68 65 20 .** hash of the
3040: 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20 74 72 entire source tr
3050: 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c ee..**.** See al
3060: 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 so: [sqlite3_lib
3070: 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b version()],.** [
3080: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 sqlite3_libversi
3090: 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 on_number()], [s
30a0: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 qlite3_sourceid(
30b0: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 )],.** [sqlite_v
30c0: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 ersion()] and [s
30d0: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 qlite_source_id(
30e0: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 )]..*/.#define S
30f0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 QLITE_VERSION
3100: 20 20 20 20 20 22 33 2e 38 2e 31 32 22 0a 23 64 "3.8.12".#d
3110: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 efine SQLITE_VER
3120: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 33 30 30 38 SION_NUMBER 3008
3130: 30 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 012.#define SQLI
3140: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 20 20 20 TE_SOURCE_ID
3150: 20 20 22 32 30 31 35 2d 30 39 2d 33 30 20 31 34 "2015-09-30 14
3160: 3a 33 30 3a 31 39 20 65 37 39 36 63 30 65 66 62 :30:19 e796c0efb
3170: 36 63 66 31 37 34 34 34 62 35 33 61 66 37 35 30 6cf17444b53af750
3180: 34 36 64 61 66 37 64 38 66 61 38 32 66 37 38 22 46daf7d8fa82f78"
3190: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
31a0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 : Run-Time Libra
31b0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 ry Version Numbe
31c0: 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 rs.** KEYWORDS:
31d0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 2c sqlite3_version,
31e0: 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 sqlite3_sourcei
31f0: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e d.**.** These in
3200: 74 65 72 66 61 63 65 73 20 70 72 6f 76 69 64 65 terfaces provide
3210: 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d the same inform
3220: 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 ation as the [SQ
3230: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a LITE_VERSION],.*
3240: 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f * [SQLITE_VERSIO
3250: 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b N_NUMBER], and [
3260: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 SQLITE_SOURCE_ID
3270: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 ] C preprocessor
3280: 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61 macros.** but a
3290: 72 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 re associated wi
32a0: 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 20 69 th the library i
32b0: 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 68 65 nstead of the he
32c0: 61 64 65 72 20 66 69 6c 65 2e 20 20 5e 28 43 61 ader file. ^(Ca
32d0: 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61 utious.** progra
32e0: 6d 6d 65 72 73 20 6d 69 67 68 74 20 69 6e 63 6c mmers might incl
32f0: 75 64 65 20 61 73 73 65 72 74 28 29 20 73 74 61 ude assert() sta
3300: 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 69 72 tements in their
3310: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a application to.
3320: 2a 2a 20 76 65 72 69 66 79 20 74 68 61 74 20 76 ** verify that v
3330: 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 alues returned b
3340: 79 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 y these interfac
3350: 65 73 20 6d 61 74 63 68 20 74 68 65 20 6d 61 63 es match the mac
3360: 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65 ros in.** the he
3370: 61 64 65 72 2c 20 61 6e 64 20 74 68 75 73 20 65 ader, and thus e
3380: 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 61 nsure that the a
3390: 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a pplication is.**
33a0: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d compiled with m
33b0: 61 74 63 68 69 6e 67 20 6c 69 62 72 61 72 79 20 atching library
33c0: 61 6e 64 20 68 65 61 64 65 72 20 66 69 6c 65 73 and header files
33d0: 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 ..**.** <blockqu
33e0: 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 ote><pre>.** ass
33f0: 65 72 74 28 20 73 71 6c 69 74 65 33 5f 6c 69 62 ert( sqlite3_lib
3400: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 version_number()
3410: 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e ==SQLITE_VERSION
3420: 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73 _NUMBER );.** as
3430: 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c sert( strcmp(sql
3440: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 2c ite3_sourceid(),
3450: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 SQLITE_SOURCE_ID
3460: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 )==0 );.** asser
3470: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 t( strcmp(sqlite
3480: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53 3_libversion(),S
3490: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d QLITE_VERSION)==
34a0: 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 0 );.** </pre></
34b0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a blockquote>)^.**
34c0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
34d0: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e _version[] strin
34e0: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 g constant conta
34f0: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 ins the text of
3500: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d [SQLITE_VERSION]
3510: 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65 .** macro. ^The
3520: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 sqlite3_libvers
3530: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 ion() function r
3540: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
3550: 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68 to the.** to th
3560: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f e sqlite3_versio
3570: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 n[] string const
3580: 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 ant. The sqlite
3590: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a 3_libversion().*
35a0: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 * function is pr
35b0: 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69 ovided for use i
35c0: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c n DLLs since DLL
35d0: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64 users usually d
35e0: 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69 o not have.** di
35f0: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73 rect access to s
3600: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 tring constants
3610: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20 within the DLL.
3620: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 ^The.** sqlite3
3630: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 _libversion_numb
3640: 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 er() function re
3650: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 turns an integer
3660: 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 equal to.** [SQ
3670: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d LITE_VERSION_NUM
3680: 42 45 52 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 BER]. ^The sqli
3690: 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20 66 te3_sourceid() f
36a0: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
36b0: 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f .** a pointer to
36c0: 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 a string consta
36d0: 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20 69 nt whose value i
36e0: 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74 68 s the same as th
36f0: 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f e .** [SQLITE_SO
3700: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 URCE_ID] C prepr
3710: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a ocessor macro..*
3720: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
3730: 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 sqlite_version()
3740: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f ] and [sqlite_so
3750: 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53 urce_id()]..*/.S
3760: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
3770: 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 char sqlite3_ver
3780: 73 69 6f 6e 5b 5d 20 3d 20 53 51 4c 49 54 45 5f sion[] = SQLITE_
3790: 56 45 52 53 49 4f 4e 3b 0a 53 51 4c 49 54 45 5f VERSION;.SQLITE_
37a0: 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a API const char *
37b0: 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
37c0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f qlite3_libversio
37d0: 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f n(void);.SQLITE_
37e0: 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a API const char *
37f0: 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
3800: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 qlite3_sourceid(
3810: 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 void);.SQLITE_AP
3820: 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
3830: 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6c 69 62 CALL sqlite3_lib
3840: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 version_number(v
3850: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 oid);../*.** CAP
3860: 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 I3REF: Run-Time
3870: 4c 69 62 72 61 72 79 20 43 6f 6d 70 69 6c 61 74 Library Compilat
3880: 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69 61 67 ion Options Diag
3890: 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 nostics.**.** ^T
38a0: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 he sqlite3_compi
38b0: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 20 leoption_used()
38c0: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
38d0: 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69 0 or 1 .** indi
38e0: 63 61 74 69 6e 67 20 77 68 65 74 68 65 72 20 74 cating whether t
38f0: 68 65 20 73 70 65 63 69 66 69 65 64 20 6f 70 74 he specified opt
3900: 69 6f 6e 20 77 61 73 20 64 65 66 69 6e 65 64 20 ion was defined
3910: 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 at .** compile t
3920: 69 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 ime. ^The SQLIT
3930: 45 5f 20 70 72 65 66 69 78 20 6d 61 79 20 62 65 E_ prefix may be
3940: 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 omitted from th
3950: 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d e .** option nam
3960: 65 20 70 61 73 73 65 64 20 74 6f 20 73 71 6c 69 e passed to sqli
3970: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f te3_compileoptio
3980: 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a n_used(). .**.*
3990: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 * ^The sqlite3_c
39a0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 ompileoption_get
39b0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f () function allo
39c0: 77 73 20 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20 ws iterating.**
39d0: 6f 76 65 72 20 74 68 65 20 6c 69 73 74 20 6f 66 over the list of
39e0: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 77 65 options that we
39f0: 72 65 20 64 65 66 69 6e 65 64 20 61 74 20 63 6f re defined at co
3a00: 6d 70 69 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a mpile time by.**
3a10: 20 72 65 74 75 72 6e 69 6e 67 20 74 68 65 20 4e returning the N
3a20: 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 -th compile time
3a30: 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20 option string.
3a40: 20 5e 49 66 20 4e 20 69 73 20 6f 75 74 20 6f 66 ^If N is out of
3a50: 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74 range,.** sqlit
3a60: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e e3_compileoption
3a70: 5f 67 65 74 28 29 20 72 65 74 75 72 6e 73 20 61 _get() returns a
3a80: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 NULL pointer.
3a90: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a ^The SQLITE_ .**
3aa0: 20 70 72 65 66 69 78 20 69 73 20 6f 6d 69 74 74 prefix is omitt
3ab0: 65 64 20 66 72 6f 6d 20 61 6e 79 20 73 74 72 69 ed from any stri
3ac0: 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 ngs returned by
3ad0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 .** sqlite3_comp
3ae0: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e ileoption_get().
3af0: 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20 .**.** ^Support
3b00: 66 6f 72 20 74 68 65 20 64 69 61 67 6e 6f 73 74 for the diagnost
3b10: 69 63 20 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c ic functions sql
3b20: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 ite3_compileopti
3b30: 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64 on_used().** and
3b40: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 sqlite3_compile
3b50: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79 option_get() may
3b60: 20 62 65 20 6f 6d 69 74 74 65 64 20 62 79 20 73 be omitted by s
3b70: 70 65 63 69 66 79 69 6e 67 20 74 68 65 20 0a 2a pecifying the .*
3b80: 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 * [SQLITE_OMIT_C
3b90: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 OMPILEOPTION_DIA
3ba0: 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f GS] option at co
3bb0: 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a mpile time..**.*
3bc0: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20 * See also: SQL
3bd0: 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74 functions [sqlit
3be0: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f e_compileoption_
3bf0: 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b used()] and.** [
3c00: 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 sqlite_compileop
3c10: 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20 tion_get()] and
3c20: 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74 the [compile_opt
3c30: 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f ions pragma]..*/
3c40: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f .#ifndef SQLITE_
3c50: 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 OMIT_COMPILEOPTI
3c60: 4f 4e 5f 44 49 41 47 53 0a 53 51 4c 49 54 45 5f ON_DIAGS.SQLITE_
3c70: 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 API int SQLITE_S
3c80: 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 TDCALL sqlite3_c
3c90: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 ompileoption_use
3ca0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f d(const char *zO
3cb0: 70 74 4e 61 6d 65 29 3b 0a 53 51 4c 49 54 45 5f ptName);.SQLITE_
3cc0: 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a API const char *
3cd0: 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
3ce0: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 qlite3_compileop
3cf0: 74 69 6f 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b tion_get(int N);
3d00: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 .#endif../*.** C
3d10: 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f API3REF: Test To
3d20: 20 53 65 65 20 49 66 20 54 68 65 20 4c 69 62 72 See If The Libr
3d30: 61 72 79 20 49 73 20 54 68 72 65 61 64 73 61 66 ary Is Threadsaf
3d40: 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c e.**.** ^The sql
3d50: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 ite3_threadsafe(
3d60: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 ) function retur
3d70: 6e 73 20 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f ns zero if and o
3d80: 6e 6c 79 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 nly if.** SQLite
3d90: 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 was compiled wi
3da0: 74 68 20 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 th mutexing code
3db0: 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74 6f 20 omitted due to
3dc0: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 the.** [SQLITE_T
3dd0: 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 HREADSAFE] compi
3de0: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 le-time option b
3df0: 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a eing set to 0..*
3e00: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 *.** SQLite can
3e10: 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 be compiled with
3e20: 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65 or without mute
3e30: 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 xes. When.** th
3e40: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 e [SQLITE_THREAD
3e50: 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65 SAFE] C preproce
3e60: 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 31 20 ssor macro is 1
3e70: 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a or 2, mutexes.**
3e80: 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 are enabled and
3e90: 20 53 51 4c 69 74 65 20 69 73 20 74 68 72 65 61 SQLite is threa
3ea0: 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74 68 65 dsafe. When the
3eb0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 .** [SQLITE_THRE
3ec0: 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 ADSAFE] macro is
3ed0: 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 0, .** the mute
3ee0: 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65 64 2e xes are omitted.
3ef0: 20 20 57 69 74 68 6f 75 74 20 74 68 65 20 6d 75 Without the mu
3f00: 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 texes, it is not
3f10: 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 safe.** to use
3f20: 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72 65 6e SQLite concurren
3f30: 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 tly from more th
3f40: 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a an one thread..*
3f50: 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 *.** Enabling mu
3f60: 74 65 78 65 73 20 69 6e 63 75 72 73 20 61 20 6d texes incurs a m
3f70: 65 61 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72 easurable perfor
3f80: 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a mance penalty..*
3f90: 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20 69 73 * So if speed is
3fa0: 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 of utmost impor
3fb0: 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 tance, it makes
3fc0: 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62 6c 65 sense to disable
3fd0: 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 2e .** the mutexes.
3fe0: 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 But for maximu
3ff0: 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65 78 65 m safety, mutexe
4000: 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 s should be enab
4010: 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 led..** ^The def
4020: 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 73 ault behavior is
4030: 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74 6f 20 for mutexes to
4040: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a be enabled..**.*
4050: 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 * This interface
4060: 20 63 61 6e 20 62 65 20 75 73 65 64 20 62 79 20 can be used by
4070: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 an application t
4080: 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 o make sure that
4090: 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 the.** version
40a0: 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 of SQLite that i
40b0: 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 t is linking aga
40c0: 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 inst was compile
40d0: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 d with.** the de
40e0: 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66 sired setting of
40f0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
4100: 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a EADSAFE] macro..
4110: 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 **.** This inter
4120: 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 face only report
4130: 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 s on the compile
4140: 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65 74 74 -time mutex sett
4150: 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 ing.** of the [S
4160: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
4170: 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 ] flag. If SQLi
4180: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
4190: 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 ith.** SQLITE_TH
41a0: 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 READSAFE=1 or =2
41b0: 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72 then mutexes ar
41c0: 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 e enabled by def
41d0: 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 ault but.** can
41e0: 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 be fully or part
41f0: 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75 ially disabled u
4200: 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b sing a call to [
4210: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
4220: 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65 ].** with the ve
4230: 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 rbs [SQLITE_CONF
4240: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d IG_SINGLETHREAD]
4250: 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 , [SQLITE_CONFIG
4260: 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a _MULTITHREAD],.*
4270: 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e * or [SQLITE_CON
4280: 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e FIG_SERIALIZED].
4290: 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e 20 76 ^(The return v
42a0: 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 alue of the.** s
42b0: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 qlite3_threadsaf
42c0: 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f e() function sho
42d0: 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 ws only the comp
42e0: 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 ile-time setting
42f0: 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 of.** thread sa
4300: 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 fety, not any ru
4310: 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73 20 74 n-time changes t
4320: 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 6d o that setting m
4330: 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 ade by.** sqlite
4340: 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 3_config(). In o
4350: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 ther words, the
4360: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f return value fro
4370: 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 m sqlite3_thread
4380: 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 safe().** is unc
4390: 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c 73 20 hanged by calls
43a0: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 to sqlite3_confi
43b0: 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 g().)^.**.** See
43c0: 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 the [threading
43d0: 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 mode] documentat
43e0: 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e ion for addition
43f0: 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a al information..
4400: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
4410: 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
4420: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 sqlite3_threads
4430: 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a afe(void);../*.*
4440: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 * CAPI3REF: Data
4450: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 base Connection
4460: 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 Handle.** KEYWOR
4470: 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f DS: {database co
4480: 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 nnection} {datab
4490: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d ase connections}
44a0: 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e .**.** Each open
44b0: 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 SQLite database
44c0: 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 is represented
44d0: 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 by a pointer to
44e0: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a an instance of.*
44f0: 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73 74 72 * the opaque str
4500: 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73 71 ucture named "sq
4510: 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73 20 75 lite3". It is u
4520: 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f seful to think o
4530: 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 f an sqlite3.**
4540: 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 pointer as an ob
4550: 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 ject. The [sqli
4560: 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 te3_open()], [sq
4570: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c lite3_open16()],
4580: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and.** [sqlite3
4590: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 _open_v2()] inte
45a0: 72 66 61 63 65 73 20 61 72 65 20 69 74 73 20 63 rfaces are its c
45b0: 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 onstructors, and
45c0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 [sqlite3_close(
45d0: 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 )].** and [sqlit
45e0: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 5d 20 61 e3_close_v2()] a
45f0: 72 65 20 69 74 73 20 64 65 73 74 72 75 63 74 6f re its destructo
4600: 72 73 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d rs. There are m
4610: 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 any other.** int
4620: 65 72 66 61 63 65 73 20 28 73 75 63 68 20 61 73 erfaces (such as
4630: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
4640: 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c pare_v2()], [sql
4650: 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
4660: 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 tion()], and.**
4670: 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 [sqlite3_busy_ti
4680: 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 meout()] to name
4690: 20 62 75 74 20 74 68 72 65 65 29 20 74 68 61 74 but three) that
46a0: 20 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 are methods on
46b0: 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 an.** sqlite3 ob
46c0: 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 ject..*/.typedef
46d0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20 struct sqlite3
46e0: 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 sqlite3;../*.**
46f0: 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74 CAPI3REF: 64-Bit
4700: 20 49 6e 74 65 67 65 72 20 54 79 70 65 73 0a 2a Integer Types.*
4710: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 * KEYWORDS: sqli
4720: 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f te_int64 sqlite_
4730: 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 uint64.**.** Bec
4740: 61 75 73 65 20 74 68 65 72 65 20 69 73 20 6e 6f ause there is no
4750: 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 cross-platform
4760: 77 61 79 20 74 6f 20 73 70 65 63 69 66 79 20 36 way to specify 6
4770: 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 74 79 4-bit integer ty
4780: 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e pes.** SQLite in
4790: 63 6c 75 64 65 73 20 74 79 70 65 64 65 66 73 20 cludes typedefs
47a0: 66 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 for 64-bit signe
47b0: 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 d and unsigned i
47c0: 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 ntegers..**.** T
47d0: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 he sqlite3_int64
47e0: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 6e and sqlite3_uin
47f0: 74 36 34 20 61 72 65 20 74 68 65 20 70 72 65 66 t64 are the pref
4800: 65 72 72 65 64 20 74 79 70 65 20 64 65 66 69 6e erred type defin
4810: 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 itions..** The s
4820: 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 qlite_int64 and
4830: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 sqlite_uint64 ty
4840: 70 65 73 20 61 72 65 20 73 75 70 70 6f 72 74 65 pes are supporte
4850: 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a d for backwards.
4860: 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 ** compatibility
4870: 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 only..**.** ^Th
4880: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 e sqlite3_int64
4890: 61 6e 64 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 and sqlite_int64
48a0: 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65 types can store
48b0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 0a integer values.
48c0: 2a 2a 20 62 65 74 77 65 65 6e 20 2d 39 32 32 33 ** between -9223
48d0: 33 37 32 30 33 36 38 35 34 37 37 35 38 30 38 20 372036854775808
48e0: 61 6e 64 20 2b 39 32 32 33 33 37 32 30 33 36 38 and +92233720368
48f0: 35 34 37 37 35 38 30 37 20 69 6e 63 6c 75 73 69 54775807 inclusi
4900: 76 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c ve. ^The.** sql
4910: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 6e 64 20 ite3_uint64 and
4920: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 sqlite_uint64 ty
4930: 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e pes can store in
4940: 74 65 67 65 72 20 76 61 6c 75 65 73 20 0a 2a 2a teger values .**
4950: 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 2b between 0 and +
4960: 31 38 34 34 36 37 34 34 30 37 33 37 30 39 35 35 1844674407370955
4970: 31 36 31 35 20 69 6e 63 6c 75 73 69 76 65 2e 0a 1615 inclusive..
4980: 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 */.#ifdef SQLITE
4990: 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 74 79 _INT64_TYPE. ty
49a0: 70 65 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 pedef SQLITE_INT
49b0: 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 69 64_TYPE sqlite_i
49c0: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 nt64;. typedef
49d0: 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f unsigned SQLITE_
49e0: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 INT64_TYPE sqlit
49f0: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 e_uint64;.#elif
4a00: 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 defined(_MSC_VER
4a10: 29 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 ) || defined(__B
4a20: 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 ORLANDC__). typ
4a30: 65 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c edef __int64 sql
4a40: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 ite_int64;. typ
4a50: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f edef unsigned __
4a60: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e int64 sqlite_uin
4a70: 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 t64;.#else. typ
4a80: 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 edef long long i
4a90: 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b nt sqlite_int64;
4aa0: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 . typedef unsig
4ab0: 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e ned long long in
4ac0: 74 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b t sqlite_uint64;
4ad0: 0a 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 .#endif.typedef
4ae0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c sqlite_int64 sql
4af0: 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 ite3_int64;.type
4b00: 64 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 def sqlite_uint6
4b10: 34 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 4 sqlite3_uint64
4b20: 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 ;../*.** If comp
4b30: 69 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 iling for a proc
4b40: 65 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 essor that lacks
4b50: 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 floating point
4b60: 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 support,.** subs
4b70: 74 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 titute integer f
4b80: 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e or floating-poin
4b90: 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c t..*/.#ifdef SQL
4ba0: 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e ITE_OMIT_FLOATIN
4bb0: 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 G_POINT.# define
4bc0: 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f double sqlite3_
4bd0: 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a int64.#endif../*
4be0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c .** CAPI3REF: Cl
4bf0: 6f 73 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 osing A Database
4c00: 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 44 Connection.** D
4c10: 45 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 ESTRUCTOR: sqlit
4c20: 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 e3.**.** ^The sq
4c30: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e lite3_close() an
4c40: 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f d sqlite3_close_
4c50: 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 v2() routines ar
4c60: 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a e destructors.**
4c70: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 for the [sqlite
4c80: 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 3] object..** ^C
4c90: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f alls to sqlite3_
4ca0: 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 close() and sqli
4cb0: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 te3_close_v2() r
4cc0: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b eturn [SQLITE_OK
4cd0: 5d 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c ] if.** the [sql
4ce0: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 ite3] object is
4cf0: 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 successfully des
4d00: 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 troyed and all a
4d10: 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 ssociated.** res
4d20: 6f 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c ources are deall
4d30: 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 ocated..**.** ^I
4d40: 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 f the database c
4d50: 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 onnection is ass
4d60: 6f 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 ociated with unf
4d70: 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 inalized prepare
4d80: 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 d.** statements
4d90: 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 or unfinished sq
4da0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a lite3_backup obj
4db0: 65 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 ects then sqlite
4dc0: 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 3_close().** wil
4dd0: 6c 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 l leave the data
4de0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
4df0: 6f 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 open and return
4e00: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a [SQLITE_BUSY]..*
4e10: 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c * ^If sqlite3_cl
4e20: 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c ose_v2() is call
4e30: 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 ed with unfinali
4e40: 7a 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 zed prepared sta
4e50: 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f 6f tements.** and/o
4e60: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c r unfinished sql
4e70: 69 74 65 33 5f 62 61 63 6b 75 70 73 2c 20 74 68 ite3_backups, th
4e80: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
4e90: 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 63 6f 6d connection becom
4ea0: 65 73 0a 2a 2a 20 61 6e 20 75 6e 75 73 61 62 6c es.** an unusabl
4eb0: 65 20 22 7a 6f 6d 62 69 65 22 20 77 68 69 63 68 e "zombie" which
4ec0: 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 will automatica
4ed0: 6c 6c 79 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 lly be deallocat
4ee0: 65 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c ed when the.** l
4ef0: 61 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 ast prepared sta
4f00: 74 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 tement is finali
4f10: 7a 65 64 20 6f 72 20 74 68 65 20 6c 61 73 74 20 zed or the last
4f20: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 69 sqlite3_backup i
4f30: 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 2e 20 20 s.** finished.
4f40: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 The sqlite3_clos
4f50: 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 e_v2() interface
4f60: 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 is intended for
4f70: 20 75 73 65 20 77 69 74 68 0a 2a 2a 20 68 6f 73 use with.** hos
4f80: 74 20 6c 61 6e 67 75 61 67 65 73 20 74 68 61 74 t languages that
4f90: 20 61 72 65 20 67 61 72 62 61 67 65 20 63 6f 6c are garbage col
4fa0: 6c 65 63 74 65 64 2c 20 61 6e 64 20 77 68 65 72 lected, and wher
4fb0: 65 20 74 68 65 20 6f 72 64 65 72 20 69 6e 20 77 e the order in w
4fc0: 68 69 63 68 0a 2a 2a 20 64 65 73 74 72 75 63 74 hich.** destruct
4fd0: 6f 72 73 20 61 72 65 20 63 61 6c 6c 65 64 20 69 ors are called i
4fe0: 73 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a s arbitrary..**.
4ff0: 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 ** Applications
5000: 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f should [sqlite3_
5010: 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c finalize | final
5020: 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 ize] all [prepar
5030: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 0a ed statements],.
5040: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 ** [sqlite3_blob
5050: 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 _close | close]
5060: 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 all [BLOB handle
5070: 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c s], and .** [sql
5080: 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 ite3_backup_fini
5090: 73 68 20 7c 20 66 69 6e 69 73 68 5d 20 61 6c 6c sh | finish] all
50a0: 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 [sqlite3_backup
50b0: 5d 20 6f 62 6a 65 63 74 73 20 61 73 73 6f 63 69 ] objects associ
50c0: 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 ated.** with the
50d0: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 [sqlite3] objec
50e0: 74 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d t prior to attem
50f0: 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 pting to close t
5100: 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a he object. ^If.
5110: 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 ** sqlite3_close
5120: 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 _v2() is called
5130: 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 on a [database c
5140: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 onnection] that
5150: 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 still has.** out
5160: 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 standing [prepar
5170: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 ed statements],
5180: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 [BLOB handles],
5190: 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 and/or.** [sqlit
51a0: 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 e3_backup] objec
51b0: 74 73 20 74 68 65 6e 20 69 74 20 72 65 74 75 72 ts then it retur
51c0: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 61 ns [SQLITE_OK] a
51d0: 6e 64 20 74 68 65 20 64 65 61 6c 6c 6f 63 61 74 nd the deallocat
51e0: 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f 75 72 ion.** of resour
51f0: 63 65 73 20 69 73 20 64 65 66 65 72 72 65 64 20 ces is deferred
5200: 75 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65 70 61 until all [prepa
5210: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c red statements],
5220: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c [BLOB handles],
5230: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 .** and [sqlite3
5240: 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 _backup] objects
5250: 20 61 72 65 20 61 6c 73 6f 20 64 65 73 74 72 6f are also destro
5260: 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 yed..**.** ^If a
5270: 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 n [sqlite3] obje
5280: 63 74 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 ct is destroyed
5290: 77 68 69 6c 65 20 61 20 74 72 61 6e 73 61 63 74 while a transact
52a0: 69 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 ion is open,.**
52b0: 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 the transaction
52c0: 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 is automatically
52d0: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a rolled back..**
52e0: 0a 2a 2a 20 54 68 65 20 43 20 70 61 72 61 6d 65 .** The C parame
52f0: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ter to [sqlite3_
5300: 63 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20 5b 73 close(C)] and [s
5310: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 qlite3_close_v2(
5320: 43 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 C)].** must be e
5330: 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 ither a NULL.**
5340: 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 pointer or an [s
5350: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 qlite3] object p
5360: 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 0a ointer obtained.
5370: 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ** from [sqlite3
5380: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 _open()], [sqlit
5390: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 e3_open16()], or
53a0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 .** [sqlite3_ope
53b0: 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 n_v2()], and not
53c0: 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 previously clos
53d0: 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 ed..** ^Calling
53e0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 sqlite3_close()
53f0: 6f 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 or sqlite3_close
5400: 5f 76 32 28 29 20 77 69 74 68 20 61 20 4e 55 4c _v2() with a NUL
5410: 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 72 67 L pointer.** arg
5420: 75 6d 65 6e 74 20 69 73 20 61 20 68 61 72 6d 6c ument is a harml
5430: 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 ess no-op..*/.SQ
5440: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
5450: 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
5460: 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 te3_close(sqlite
5470: 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 3*);.SQLITE_API
5480: 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 int SQLITE_STDCA
5490: 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 LL sqlite3_close
54a0: 5f 76 32 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a _v2(sqlite3*);..
54b0: 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 /*.** The type f
54c0: 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 or a callback fu
54d0: 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 nction..** This
54e0: 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 is legacy and de
54f0: 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 precated. It is
5500: 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 included for hi
5510: 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 storical.** comp
5520: 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 atibility and is
5530: 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e not documented.
5540: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 .*/.typedef int
5550: 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 (*sqlite3_callba
5560: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 ck)(void*,int,ch
5570: 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a ar**, char**);..
5580: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
5590: 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 One-Step Query E
55a0: 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 xecution Interfa
55b0: 63 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 ce.** METHOD: sq
55c0: 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 lite3.**.** The
55d0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 sqlite3_exec() i
55e0: 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f nterface is a co
55f0: 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65 nvenience wrappe
5600: 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c r around.** [sql
5610: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
5620: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 )], [sqlite3_ste
5630: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 p()], and [sqlit
5640: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a e3_finalize()],.
5650: 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61 ** that allows a
5660: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f n application to
5670: 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74 run multiple st
5680: 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a atements of SQL.
5690: 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e ** without havin
56a0: 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f g to use a lot o
56b0: 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a f C code. .**.**
56c0: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 ^The sqlite3_ex
56d0: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 ec() interface r
56e0: 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 uns zero or more
56f0: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a UTF-8 encoded,.
5700: 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 ** semicolon-sep
5710: 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d arate SQL statem
5720: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f ents passed into
5730: 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e its 2nd argumen
5740: 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e t,.** in the con
5750: 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74 text of the [dat
5760: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
5770: 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 69 ] passed in as i
5780: 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65 ts 1st.** argume
5790: 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c nt. ^If the cal
57a0: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f lback function o
57b0: 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65 f the 3rd argume
57c0: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 nt to.** sqlite3
57d0: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e _exec() is not N
57e0: 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20 ULL, then it is
57f0: 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68 invoked for each
5800: 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 result row.** c
5810: 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65 oming out of the
5820: 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73 evaluated SQL s
5830: 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65 tatements. ^The
5840: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 4th argument to
5850: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 .** sqlite3_exec
5860: 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 () is relayed th
5870: 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 rough to the 1st
5880: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 argument of eac
5890: 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e h.** callback in
58a0: 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 vocation. ^If t
58b0: 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e he callback poin
58c0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 ter to sqlite3_e
58d0: 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c xec().** is NULL
58e0: 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 , then no callba
58f0: 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b ck is ever invok
5900: 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f ed and result ro
5910: 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 ws are.** ignore
5920: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 d..**.** ^If an
5930: 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 error occurs whi
5940: 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 le evaluating th
5950: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 e SQL statements
5960: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 passed into.**
5970: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 sqlite3_exec(),
5980: 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f then execution o
5990: 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 f the current st
59a0: 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e atement stops an
59b0: 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 d.** subsequent
59c0: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 statements are s
59d0: 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 kipped. ^If the
59e0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 5th parameter t
59f0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 o sqlite3_exec()
5a00: 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 .** is not NULL
5a10: 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d then any error m
5a20: 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65 essage is writte
5a30: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 n into memory ob
5a40: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b tained.** from [
5a50: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
5a60: 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 ] and passed bac
5a70: 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 k through the 5t
5a80: 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 h parameter..**
5a90: 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 To avoid memory
5aa0: 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 leaks, the appli
5ab0: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e cation should in
5ac0: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 voke [sqlite3_fr
5ad0: 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f ee()].** on erro
5ae0: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 r message string
5af0: 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 s returned throu
5b00: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d gh the 5th param
5b10: 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 eter of.** of sq
5b20: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 lite3_exec() aft
5b30: 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 er the error mes
5b40: 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e sage string is n
5b50: 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e o longer needed.
5b60: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 .** ^If the 5th
5b70: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
5b80: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e ite3_exec() is n
5b90: 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 ot NULL and no e
5ba0: 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 rrors.** occur,
5bb0: 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 then sqlite3_exe
5bc0: 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 c() sets the poi
5bd0: 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 nter in its 5th
5be0: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 parameter to.**
5bf0: 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 NULL before retu
5c00: 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 rning..**.** ^If
5c10: 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 an sqlite3_exec
5c20: 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 () callback retu
5c30: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 rns non-zero, th
5c40: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 e sqlite3_exec()
5c50: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 .** routine retu
5c60: 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 rns SQLITE_ABORT
5c70: 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e without invokin
5c80: 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 g the callback a
5c90: 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 gain and.** with
5ca0: 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 out running any
5cb0: 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 subsequent SQL s
5cc0: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a tatements..**.**
5cd0: 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 ^The 2nd argume
5ce0: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 nt to the sqlite
5cf0: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 3_exec() callbac
5d00: 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 k function is th
5d10: 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 e.** number of c
5d20: 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 olumns in the re
5d30: 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 sult. ^The 3rd
5d40: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 argument to the
5d50: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a sqlite3_exec().*
5d60: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e * callback is an
5d70: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 array of pointe
5d80: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 rs to strings ob
5d90: 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f tained as if fro
5da0: 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f m.** [sqlite3_co
5db0: 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e lumn_text()], on
5dc0: 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d e for each colum
5dd0: 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 n. ^If an eleme
5de0: 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c nt of a.** resul
5df0: 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 t row is NULL th
5e00: 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e en the correspon
5e10: 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e ding string poin
5e20: 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 ter for the.** s
5e30: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 qlite3_exec() ca
5e40: 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c llback is a NULL
5e50: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 pointer. ^The
5e60: 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 4th argument to
5e70: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 the.** sqlite3_e
5e80: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 xec() callback i
5e90: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f s an array of po
5ea0: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 inters to string
5eb0: 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 s where each.**
5ec0: 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 entry represents
5ed0: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 the name of cor
5ee0: 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c responding resul
5ef0: 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 t column as obta
5f00: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 ined.** from [sq
5f10: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d lite3_column_nam
5f20: 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 e()]..**.** ^If
5f30: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 the 2nd paramete
5f40: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 r to sqlite3_exe
5f50: 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f c() is a NULL po
5f60: 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 inter, a pointer
5f70: 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 .** to an empty
5f80: 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 string, or a poi
5f90: 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 nter that contai
5fa0: 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 ns only whitespa
5fb0: 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 ce and/or .** SQ
5fc0: 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e L comments, then
5fd0: 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e no SQL statemen
5fe0: 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 ts are evaluated
5ff0: 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 and the databas
6000: 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e e.** is not chan
6010: 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 ged..**.** Restr
6020: 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c ictions:.**.** <
6030: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 ul>.** <li> The
6040: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 application must
6050: 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 ensure that the
6060: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 1st parameter t
6070: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 o sqlite3_exec()
6080: 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 .** is a va
6090: 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 lid and open [da
60a0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
60b0: 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 n]..** <li> The
60c0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 application must
60d0: 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 5b not close the [
60e0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
60f0: 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 ion] specified b
6100: 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73 y.** the 1s
6110: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 t parameter to s
6120: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 qlite3_exec() wh
6130: 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 ile sqlite3_exec
6140: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a () is running..*
6150: 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 * <li> The appli
6160: 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 cation must not
6170: 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 73 modify the SQL s
6180: 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61 tatement text pa
6190: 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 ssed into.**
61a0: 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 the 2nd parame
61b0: 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 ter of sqlite3_e
61c0: 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 xec() while sqli
61d0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 te3_exec() is ru
61e0: 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a nning..** </ul>.
61f0: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
6200: 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
6210: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 sqlite3_exec(.
6220: 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 sqlite3*,
6230: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
6240: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 /* A
6250: 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 n open database
6260: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
6270: 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 *sql,
6280: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
6290: 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 /* SQL to be eva
62a0: 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 luated */. int
62b0: 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 (*callback)(void
62c0: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 *,int,char**,cha
62d0: 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 r**), /* Callba
62e0: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 ck function */.
62f0: 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 void *,
6300: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
6310: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31 /* 1
6320: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 st argument to c
6330: 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 allback */. cha
6340: 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 r **errmsg
6350: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
6360: 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 /* Error
6370: 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 msg written her
6380: 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 e */.);../*.** C
6390: 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 API3REF: Result
63a0: 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 Codes.** KEYWORD
63b0: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 20 S: {result code
63c0: 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a definitions}.**.
63d0: 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 ** Many SQLite f
63e0: 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 unctions return
63f0: 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c an integer resul
6400: 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 t code from the
6410: 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 set shown.** her
6420: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e e in order to in
6430: 64 69 63 61 74 65 20 73 75 63 63 65 73 73 20 6f dicate success o
6440: 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a r failure..**.**
6450: 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 New error codes
6460: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e may be added in
6470: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 future versions
6480: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a of SQLite..**.*
6490: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74 * See also: [ext
64a0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
64b0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a e definitions].*
64c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
64d0: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 _OK 0
64e0: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 /* Successful
64f0: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 result */./* beg
6500: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d inning-of-error-
6510: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 codes */.#define
6520: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 SQLITE_ERROR
6530: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 1 /* SQL
6540: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 error or missing
6550: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 database */.#de
6560: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 fine SQLITE_INTE
6570: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 RNAL 2 /*
6580: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 Internal logic e
6590: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a rror in SQLite *
65a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
65b0: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20 _PERM 3
65c0: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d /* Access perm
65d0: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f ission denied */
65e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
65f0: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20 ABORT 4
6600: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 /* Callback rou
6610: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61 tine requested a
6620: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 n abort */.#defi
6630: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20 ne SQLITE_BUSY
6640: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68 5 /* Th
6650: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
6660: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 is locked */.#de
6670: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b fine SQLITE_LOCK
6680: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20 ED 6 /*
6690: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64 A table in the d
66a0: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 atabase is locke
66b0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
66c0: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 ITE_NOMEM
66d0: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 7 /* A malloc
66e0: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 () failed */.#de
66f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 fine SQLITE_READ
6700: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20 ONLY 8 /*
6710: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 Attempt to write
6720: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 a readonly data
6730: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 base */.#define
6740: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 SQLITE_INTERRUPT
6750: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 9 /* Opera
6760: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 tion terminated
6770: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 by sqlite3_inter
6780: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 rupt()*/.#define
6790: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 SQLITE_IOERR
67a0: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 10 /* Some
67b0: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f kind of disk I/
67c0: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64 O error occurred
67d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
67e0: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31 TE_CORRUPT 1
67f0: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 1 /* The datab
6800: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69 ase disk image i
6810: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 s malformed */.#
6820: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f define SQLITE_NO
6830: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f TFOUND 12 /
6840: 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 * Unknown opcode
6850: 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 in sqlite3_file
6860: 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 _control() */.#d
6870: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c efine SQLITE_FUL
6880: 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a L 13 /*
6890: 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 Insertion faile
68a0: 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61 d because databa
68b0: 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 se is full */.#d
68c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e efine SQLITE_CAN
68d0: 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a TOPEN 14 /*
68e0: 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 Unable to open
68f0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
6900: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c e */.#define SQL
6910: 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 ITE_PROTOCOL
6920: 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 15 /* Database
6930: 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 lock protocol e
6940: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 rror */.#define
6950: 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 SQLITE_EMPTY
6960: 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 16 /* Datab
6970: 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a ase is empty */.
6980: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
6990: 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 CHEMA 17
69a0: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 /* The database
69b0: 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a schema changed *
69c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
69d0: 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 _TOOBIG 18
69e0: 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 /* String or B
69f0: 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 LOB exceeds size
6a00: 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e limit */.#defin
6a10: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 e SQLITE_CONSTRA
6a20: 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f INT 19 /* Abo
6a30: 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 rt due to constr
6a40: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a aint violation *
6a50: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
6a60: 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 _MISMATCH 20
6a70: 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d /* Data type m
6a80: 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 ismatch */.#defi
6a90: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 ne SQLITE_MISUSE
6aa0: 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 21 /* Li
6ab0: 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 brary used incor
6ac0: 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e rectly */.#defin
6ad0: 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 e SQLITE_NOLFS
6ae0: 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 22 /* Use
6af0: 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f s OS features no
6b00: 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 t supported on h
6b10: 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ost */.#define S
6b20: 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 QLITE_AUTH
6b30: 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 23 /* Author
6b40: 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a ization denied *
6b50: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
6b60: 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 _FORMAT 24
6b70: 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 /* Auxiliary d
6b80: 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 atabase format e
6b90: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 rror */.#define
6ba0: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 SQLITE_RANGE
6bb0: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 25 /* 2nd p
6bc0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
6bd0: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 te3_bind out of
6be0: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 range */.#define
6bf0: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 SQLITE_NOTADB
6c00: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 26 /* File
6c10: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 opened that is
6c20: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66 not a database f
6c30: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ile */.#define S
6c40: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20 QLITE_NOTICE
6c50: 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69 27 /* Notifi
6c60: 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c cations from sql
6c70: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 ite3_log() */.#d
6c80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 efine SQLITE_WAR
6c90: 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a NING 28 /*
6ca0: 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73 Warnings from s
6cb0: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a qlite3_log() */.
6cc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
6cd0: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20 OW 100
6ce0: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 /* sqlite3_step(
6cf0: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f ) has another ro
6d00: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 w ready */.#defi
6d10: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 ne SQLITE_DONE
6d20: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 101 /* sq
6d30: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 lite3_step() has
6d40: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 finished execut
6d50: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 ing */./* end-of
6d60: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a -error-codes */.
6d70: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
6d80: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 Extended Result
6d90: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 Codes.** KEYWOR
6da0: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65 DS: {extended re
6db0: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 sult code defini
6dc0: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 tions}.**.** In
6dd0: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 its default conf
6de0: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 iguration, SQLit
6df0: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 e API routines r
6e00: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20 eturn one of 30
6e10: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75 integer.** [resu
6e20: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 lt codes]. Howe
6e30: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 ver, experience
6e40: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d has shown that m
6e50: 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 any of.** these
6e60: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 result codes are
6e70: 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 too coarse-grai
6e80: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f ned. They do no
6e90: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 t provide as.**
6ea0: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e much information
6eb0: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 about problems
6ec0: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d as programmers m
6ed0: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 ight like. In a
6ee0: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 n effort to.** a
6ef0: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 ddress this, new
6f00: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 er versions of S
6f10: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 QLite (version 3
6f20: 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20 .3.8 and later)
6f30: 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f include.** suppo
6f40: 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 rt for additiona
6f50: 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 l result codes t
6f60: 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 hat provide more
6f70: 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d detailed inform
6f80: 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 ation.** about e
6f90: 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b 65 78 rrors. These [ex
6fa0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
6fb0: 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64 des] are enabled
6fc0: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 or disabled.**
6fd0: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73 on a per databas
6fe0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 e connection bas
6ff0: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 is using the.**
7000: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 [sqlite3_extende
7010: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 d_result_codes()
7020: 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68 65 20 ] API. Or, the
7030: 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20 66 6f extended code fo
7040: 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65 r.** the most re
7050: 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e 20 62 cent error can b
7060: 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69 6e 67 e obtained using
7070: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 .** [sqlite3_ext
7080: 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d ended_errcode()]
7090: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
70a0: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 ITE_IOERR_READ
70b0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
70c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c ITE_IOERR | (1<<
70d0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
70e0: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 TE_IOERR_SHORT_R
70f0: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 EAD (SQLI
7100: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 TE_IOERR | (2<<8
7110: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
7120: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 E_IOERR_WRITE
7130: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
7140: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 E_IOERR | (3<<8)
7150: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
7160: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 _IOERR_FSYNC
7170: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
7180: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 _IOERR | (4<<8))
7190: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
71a0: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 IOERR_DIR_FSYNC
71b0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
71c0: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a IOERR | (5<<8)).
71d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
71e0: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 OERR_TRUNCATE
71f0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
7200: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 OERR | (6<<8)).#
7210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
7220: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 ERR_FSTAT
7230: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
7240: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 ERR | (7<<8)).#d
7250: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
7260: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 RR_UNLOCK
7270: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
7280: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 RR | (8<<8)).#de
7290: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
72a0: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 R_RDLOCK
72b0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
72c0: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 R | (9<<8)).#def
72d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
72e0: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 _DELETE
72f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
7300: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 | (10<<8)).#def
7310: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
7320: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 _BLOCKED
7330: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
7340: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 | (11<<8)).#def
7350: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
7360: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 _NOMEM
7370: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
7380: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 | (12<<8)).#def
7390: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
73a0: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20 _ACCESS
73b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
73c0: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 | (13<<8)).#def
73d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
73e0: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f _CHECKRESERVEDLO
73f0: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 CK (SQLITE_IOERR
7400: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 | (14<<8)).#def
7410: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
7420: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 _LOCK
7430: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
7440: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 | (15<<8)).#def
7450: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
7460: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20 _CLOSE
7470: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
7480: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 | (16<<8)).#def
7490: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
74a0: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 _DIR_CLOSE
74b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
74c0: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 | (17<<8)).#def
74d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
74e0: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 _SHMOPEN
74f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
7500: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 | (18<<8)).#def
7510: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
7520: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20 _SHMSIZE
7530: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
7540: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 | (19<<8)).#def
7550: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
7560: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 _SHMLOCK
7570: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
7580: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 | (20<<8)).#def
7590: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
75a0: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20 _SHMMAP
75b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
75c0: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 | (21<<8)).#def
75d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
75e0: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20 _SEEK
75f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
7600: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 | (22<<8)).#def
7610: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
7620: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 _DELETE_NOENT
7630: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
7640: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 | (23<<8)).#def
7650: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
7660: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 _MMAP
7670: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
7680: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 | (24<<8)).#def
7690: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
76a0: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20 _GETTEMPPATH
76b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
76c0: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 | (25<<8)).#def
76d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
76e0: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 _CONVPATH
76f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
7700: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 | (26<<8)).#def
7710: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
7720: 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20 _VNODE
7730: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
7740: 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66 | (27<<8)).#def
7750: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 ine SQLITE_LOCKE
7760: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 D_SHAREDCACHE
7770: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 (SQLITE_LOCKE
7780: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 D | (1<<8)).#de
7790: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 fine SQLITE_BUSY
77a0: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 _RECOVERY
77b0: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 (SQLITE_BUSY
77c0: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 | (1<<8)).#d
77d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 efine SQLITE_BUS
77e0: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20 Y_SNAPSHOT
77f0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 (SQLITE_BUS
7800: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 Y | (2<<8)).#
7810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 define SQLITE_CA
7820: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 NTOPEN_NOTEMPDIR
7830: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 (SQLITE_CA
7840: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 NTOPEN | (1<<8))
7850: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
7860: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 CANTOPEN_ISDIR
7870: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
7880: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 CANTOPEN | (2<<8
7890: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
78a0: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 E_CANTOPEN_FULLP
78b0: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 ATH (SQLIT
78c0: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c E_CANTOPEN | (3<
78d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
78e0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e ITE_CANTOPEN_CON
78f0: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c VPATH (SQL
7900: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 ITE_CANTOPEN | (
7910: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 4<<8)).#define S
7920: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 QLITE_CORRUPT_VT
7930: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53 AB (S
7940: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 QLITE_CORRUPT |
7950: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (1<<8)).#define
7960: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f SQLITE_READONLY_
7970: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28 RECOVERY (
7980: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 SQLITE_READONLY
7990: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (1<<8)).#defin
79a0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c e SQLITE_READONL
79b0: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 Y_CANTLOCK
79c0: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c (SQLITE_READONL
79d0: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 Y | (2<<8)).#def
79e0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f ine SQLITE_READO
79f0: 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 NLY_ROLLBACK
7a00: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f (SQLITE_READO
7a10: 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 NLY | (3<<8)).#d
7a20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 efine SQLITE_REA
7a30: 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20 DONLY_DBMOVED
7a40: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 (SQLITE_REA
7a50: 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a DONLY | (4<<8)).
7a60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
7a70: 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 BORT_ROLLBACK
7a80: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 (SQLITE_A
7a90: 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 BORT | (2<<8)).#
7aa0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
7ab0: 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 NSTRAINT_CHECK
7ac0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f (SQLITE_CO
7ad0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 NSTRAINT | (1<<8
7ae0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
7af0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d E_CONSTRAINT_COM
7b00: 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 MITHOOK (SQLIT
7b10: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 E_CONSTRAINT | (
7b20: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 2<<8)).#define S
7b30: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
7b40: 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53 _FOREIGNKEY (S
7b50: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
7b60: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 | (3<<8)).#defi
7b70: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 ne SQLITE_CONSTR
7b80: 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 AINT_FUNCTION
7b90: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 (SQLITE_CONSTR
7ba0: 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 AINT | (4<<8)).#
7bb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
7bc0: 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c NSTRAINT_NOTNULL
7bd0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f (SQLITE_CO
7be0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 NSTRAINT | (5<<8
7bf0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
7c00: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 E_CONSTRAINT_PRI
7c10: 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54 MARYKEY (SQLIT
7c20: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 E_CONSTRAINT | (
7c30: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 6<<8)).#define S
7c40: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
7c50: 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53 _TRIGGER (S
7c60: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
7c70: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 | (7<<8)).#defi
7c80: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 ne SQLITE_CONSTR
7c90: 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20 AINT_UNIQUE
7ca0: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 (SQLITE_CONSTR
7cb0: 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 AINT | (8<<8)).#
7cc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
7cd0: 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20 NSTRAINT_VTAB
7ce0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f (SQLITE_CO
7cf0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 NSTRAINT | (9<<8
7d00: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
7d10: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57 E_CONSTRAINT_ROW
7d20: 49 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 ID (SQLIT
7d30: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31 E_CONSTRAINT |(1
7d40: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 0<<8)).#define S
7d50: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 QLITE_NOTICE_REC
7d60: 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53 OVER_WAL (S
7d70: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 QLITE_NOTICE | (
7d80: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 1<<8)).#define S
7d90: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 QLITE_NOTICE_REC
7da0: 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 OVER_ROLLBACK (S
7db0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 QLITE_NOTICE | (
7dc0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 2<<8)).#define S
7dd0: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55 QLITE_WARNING_AU
7de0: 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28 53 TOINDEX (S
7df0: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20 QLITE_WARNING |
7e00: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (1<<8)).#define
7e10: 53 51 4c 49 54 45 5f 41 55 54 48 5f 55 53 45 52 SQLITE_AUTH_USER
7e20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 (
7e30: 53 51 4c 49 54 45 5f 41 55 54 48 20 7c 20 28 31 SQLITE_AUTH | (1
7e40: 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 <<8))../*.** CAP
7e50: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 I3REF: Flags For
7e60: 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 File Open Opera
7e70: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 tions.**.** Thes
7e80: 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 e bit values are
7e90: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 intended for us
7ea0: 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 e in the.** 3rd
7eb0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
7ec0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
7ed0: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 2()] interface a
7ee0: 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 nd.** in the 4th
7ef0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
7f00: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 e [sqlite3_vfs.x
7f10: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f Open] method..*/
7f20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
7f30: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 OPEN_READONLY
7f40: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0x00000001
7f50: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
7f60: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
7f70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
7f80: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 OPEN_READWRITE
7f90: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0x00000002
7fa0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
7fb0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
7fc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
7fd0: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 OPEN_CREATE
7fe0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0x00000004
7ff0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
8000: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
8010: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
8020: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f OPEN_DELETEONCLO
8030: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38 SE 0x00000008
8040: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
8050: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
8060: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 OPEN_EXCLUSIVE
8070: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0x00000010
8080: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
8090: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
80a0: 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 OPEN_AUTOPROXY
80b0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0x00000020
80c0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
80d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
80e0: 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20 OPEN_URI
80f0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0x00000040
8100: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
8110: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
8120: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
8130: 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 OPEN_MEMORY
8140: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0x00000080
8150: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
8160: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
8170: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
8180: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 OPEN_MAIN_DB
8190: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0x00000100
81a0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
81b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
81c0: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 OPEN_TEMP_DB
81d0: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0x00000200
81e0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
81f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
8200: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 OPEN_TRANSIENT_D
8210: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 B 0x00000400
8220: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
8230: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
8240: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 OPEN_MAIN_JOURNA
8250: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30 L 0x00000800
8260: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
8270: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
8280: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 OPEN_TEMP_JOURNA
8290: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30 L 0x00001000
82a0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
82b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
82c0: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 OPEN_SUBJOURNAL
82d0: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0x00002000
82e0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
82f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
8300: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 OPEN_MASTER_JOUR
8310: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 NAL 0x00004000
8320: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
8330: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
8340: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 OPEN_NOMUTEX
8350: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30 0x00008000
8360: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
8370: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
8380: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
8390: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 OPEN_FULLMUTEX
83a0: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30 0x00010000
83b0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
83c0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
83d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
83e0: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 OPEN_SHAREDCACHE
83f0: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30 0x00020000
8400: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
8410: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
8420: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
8430: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 OPEN_PRIVATECACH
8440: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30 E 0x00040000
8450: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
8460: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
8470: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
8480: 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 OPEN_WAL
8490: 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30 0x00080000
84a0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
84b0: 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20 ../* Reserved:
84c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
84d0: 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30 0x00F0000
84e0: 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 0 */../*.** CAPI
84f0: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 3REF: Device Cha
8500: 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a racteristics.**.
8510: 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68 ** The xDeviceCh
8520: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 aracteristics me
8530: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c thod of the [sql
8540: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d ite3_io_methods]
8550: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 .** object retur
8560: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 ns an integer wh
8570: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 ich is a vector
8580: 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 of these.** bit
8590: 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e values expressin
85a0: 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 g I/O characteri
85b0: 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 stics of the mas
85c0: 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 s storage.** dev
85d0: 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 ice that holds t
85e0: 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 he file that the
85f0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 [sqlite3_io_met
8600: 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 hods].** refers
8610: 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 to..**.** The SQ
8620: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
8630: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 C property means
8640: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 that all writes
8650: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 of.** any size
8660: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 are atomic. The
8670: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
8680: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a OMICnnn values.*
8690: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 * mean that writ
86a0: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 es of blocks tha
86b0: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 t are nnn bytes
86c0: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 in size and.** a
86d0: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e re aligned to an
86e0: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 address which i
86f0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c s an integer mul
8700: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 tiple of.** nnn
8710: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 are atomic. The
8720: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 SQLITE_IOCAP_SA
8730: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 FE_APPEND value
8740: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 means.** that wh
8750: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e en data is appen
8760: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 ded to a file, t
8770: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e he data is appen
8780: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 ded.** first the
8790: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 n the size of th
87a0: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 e file is extend
87b0: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 ed, never the ot
87c0: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e her.** way aroun
87d0: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 d. The SQLITE_I
87e0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 OCAP_SEQUENTIAL
87f0: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 property means t
8800: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 hat.** informati
8810: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f on is written to
8820: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d disk in the sam
8830: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 e order as calls
8840: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e .** to xWrite().
8850: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 The SQLITE_IOC
8860: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 AP_POWERSAFE_OVE
8870: 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 79 20 RWRITE property
8880: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 means that.** af
8890: 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f ter reboot follo
88a0: 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20 wing a crash or
88b0: 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 power loss, the
88c0: 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a only bytes in a.
88d0: 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65 72 ** file that wer
88e0: 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 68 65 e written at the
88f0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 application lev
8900: 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63 68 el might have ch
8910: 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 anged.** and tha
8920: 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73 t adjacent bytes
8930: 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 69 74 , even bytes wit
8940: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63 hin the same sec
8950: 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 tor are.** guara
8960: 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68 nteed to be unch
8970: 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c 49 anged. The SQLI
8980: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 TE_IOCAP_UNDELET
8990: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a ABLE_WHEN_OPEN.*
89a0: 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65 20 * flag indicate
89b0: 74 68 61 74 20 61 20 66 69 6c 65 20 63 61 6e 6e that a file cann
89c0: 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20 77 68 ot be deleted wh
89d0: 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a en open. The.**
89e0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d SQLITE_IOCAP_IM
89f0: 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 69 6e 64 MUTABLE flag ind
8a00: 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20 icates that the
8a10: 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65 file is on.** re
8a20: 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e ad-only media an
8a30: 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e d cannot be chan
8a40: 67 65 64 20 65 76 65 6e 20 62 79 20 70 72 6f 63 ged even by proc
8a50: 65 73 73 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c esses with.** el
8a60: 65 76 61 74 65 64 20 70 72 69 76 69 6c 65 67 65 evated privilege
8a70: 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 s..*/.#define SQ
8a80: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
8a90: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 C
8aa0: 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 0x00000001.#de
8ab0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
8ac0: 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 P_ATOMIC512
8ad0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
8ae0: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 002.#define SQLI
8af0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 TE_IOCAP_ATOMIC1
8b00: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 K
8b10: 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 0x00000004.#defi
8b20: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
8b30: 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 ATOMIC2K
8b40: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 0x0000000
8b50: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 8.#define SQLITE
8b60: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 _IOCAP_ATOMIC4K
8b70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 0x
8b80: 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 00000010.#define
8b90: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
8ba0: 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20 20 OMIC8K
8bb0: 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 0x00000020.
8bc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
8bd0: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 OCAP_ATOMIC16K
8be0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
8bf0: 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 000040.#define S
8c00: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
8c10: 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 20 20 IC32K
8c20: 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 0x00000080.#d
8c30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
8c40: 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 AP_ATOMIC64K
8c50: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
8c60: 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0100.#define SQL
8c70: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 ITE_IOCAP_SAFE_A
8c80: 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 20 20 PPEND
8c90: 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 0x00000200.#def
8ca0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
8cb0: 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 _SEQUENTIAL
8cc0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 34 0x000004
8cd0: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 00.#define SQLIT
8ce0: 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 E_IOCAP_UNDELETA
8cf0: 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 BLE_WHEN_OPEN 0
8d00: 78 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e x00000800.#defin
8d10: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 e SQLITE_IOCAP_P
8d20: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 OWERSAFE_OVERWRI
8d30: 54 45 20 20 20 20 30 78 30 30 30 30 31 30 30 30 TE 0x00001000
8d40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
8d50: 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 IOCAP_IMMUTABLE
8d60: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 0x0
8d70: 30 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 0002000../*.** C
8d80: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f API3REF: File Lo
8d90: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a cking Levels.**.
8da0: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f ** SQLite uses o
8db0: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 ne of these inte
8dc0: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 ger values as th
8dd0: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 e second.** argu
8de0: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 ment to calls it
8df0: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c makes to the xL
8e00: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 ock() and xUnloc
8e10: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f k() methods.** o
8e20: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f f an [sqlite3_io
8e30: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 _methods] object
8e40: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
8e50: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 ITE_LOCK_NONE
8e60: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 0.#define
8e70: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 SQLITE_LOCK_SHA
8e80: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 RED 1.#de
8e90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b fine SQLITE_LOCK
8ea0: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32 _RESERVED 2
8eb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
8ec0: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 LOCK_PENDING
8ed0: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 3.#define SQL
8ee0: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 ITE_LOCK_EXCLUSI
8ef0: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 VE 4../*.**
8f00: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 CAPI3REF: Synchr
8f10: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 onization Type F
8f20: 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 lags.**.** When
8f30: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 SQLite invokes t
8f40: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f he xSync() metho
8f50: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 d of an.** [sqli
8f60: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 te3_io_methods]
8f70: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 object it uses a
8f80: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a combination of.
8f90: 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 ** these integer
8fa0: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 values as the s
8fb0: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a econd argument..
8fc0: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 **.** When the S
8fd0: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f QLITE_SYNC_DATAO
8fe0: 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 NLY flag is used
8ff0: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 , it means that
9000: 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 the.** sync oper
9010: 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 ation only needs
9020: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 to flush data t
9030: 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 o mass storage.
9040: 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d Inode.** inform
9050: 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 ation need not b
9060: 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 e flushed. If th
9070: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 e lower four bit
9080: 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a s of the flag.**
9090: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 equal SQLITE_SY
90a0: 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 NC_NORMAL, that
90b0: 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 means to use nor
90c0: 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 mal fsync() sema
90d0: 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 ntics..** If the
90e0: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 lower four bits
90f0: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 equal SQLITE_SY
9100: 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 NC_FULL, that me
9110: 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 ans.** to use Ma
9120: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c c OS X style ful
9130: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 lsync instead of
9140: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 fsync()..**.**
9150: 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 Do not confuse t
9160: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e he SQLITE_SYNC_N
9170: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 ORMAL and SQLITE
9180: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 _SYNC_FULL flags
9190: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 .** with the [PR
91a0: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 AGMA synchronous
91b0: 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 ]=NORMAL and [PR
91c0: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 AGMA synchronous
91d0: 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e ]=FULL.** settin
91e0: 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 gs. The [synchr
91f0: 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 onous pragma] de
9200: 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 termines when ca
9210: 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 lls to the.** xS
9220: 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f ync VFS method o
9230: 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 ccur and applies
9240: 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 uniformly acros
9250: 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e s all platforms.
9260: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 .** The SQLITE_S
9270: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 YNC_NORMAL and S
9280: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 QLITE_SYNC_FULL
9290: 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 flags determine
92a0: 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 how.** energetic
92b0: 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 or rigorous or
92c0: 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e forceful the syn
92d0: 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 c operations are
92e0: 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b and.** only mak
92f0: 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f e a difference o
9300: 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 n Mac OSX for th
9310: 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 e default SQLite
9320: 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 code..** (Third
9330: 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 -party VFS imple
9340: 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 mentations might
9350: 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 also make the d
9360: 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 istinction.** be
9370: 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e tween SQLITE_SYN
9380: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c C_NORMAL and SQL
9390: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 ITE_SYNC_FULL, b
93a0: 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 ut among the.**
93b0: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d operating system
93c0: 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f s natively suppo
93d0: 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 rted by SQLite,
93e0: 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 only Mac OSX.**
93f0: 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 cares about the
9400: 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a difference.).*/.
9410: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
9420: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 YNC_NORMAL
9430: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 0x00002.#defin
9440: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 e SQLITE_SYNC_FU
9450: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30 LL 0x00
9460: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 003.#define SQLI
9470: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 TE_SYNC_DATAONLY
9480: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 0x00010../
9490: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
94a0: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e S Interface Open
94b0: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a File Handle.**.
94c0: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 ** An [sqlite3_f
94d0: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 ile] object repr
94e0: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 esents an open f
94f0: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b ile in the .** [
9500: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 sqlite3_vfs | OS
9510: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 interface layer
9520: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f ]. Individual O
9530: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 S interface.** i
9540: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 mplementations w
9550: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 ill.** want to s
9560: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a ubclass this obj
9570: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 ect by appending
9580: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c additional fiel
9590: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 ds.** for their
95a0: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d own use. The pM
95b0: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 ethods entry is
95c0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a a pointer to an.
95d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d ** [sqlite3_io_m
95e0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 ethods] object t
95f0: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 hat defines meth
9600: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 ods for performi
9610: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 ng.** I/O operat
9620: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e ions on the open
9630: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 file..*/.typede
9640: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
9650: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 _file sqlite3_fi
9660: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 le;.struct sqlit
9670: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 e3_file {. cons
9680: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 t struct sqlite3
9690: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 _io_methods *pMe
96a0: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f thods; /* Metho
96b0: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 ds for an open f
96c0: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a ile */.};../*.**
96d0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e CAPI3REF: OS In
96e0: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 terface File Vir
96f0: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a tual Methods Obj
9700: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 ect.**.** Every
9710: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 file opened by t
9720: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e he [sqlite3_vfs.
9730: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f xOpen] method po
9740: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 pulates an.** [s
9750: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a qlite3_file] obj
9760: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f ect (or, more co
9770: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 mmonly, a subcla
9780: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 ss of the.** [sq
9790: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 lite3_file] obje
97a0: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 ct) with a point
97b0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 er to an instanc
97c0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 e of this object
97d0: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 ..** This object
97e0: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 defines the met
97f0: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 hods used to per
9800: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 form various ope
9810: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e rations.** again
9820: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 st the open file
9830: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 represented by
9840: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c the [sqlite3_fil
9850: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a e] object..**.**
9860: 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 If the [sqlite3
9870: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 _vfs.xOpen] meth
9880: 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 od sets the sqli
9890: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 te3_file.pMethod
98a0: 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f s element .** to
98b0: 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e a non-NULL poin
98c0: 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 ter, then the sq
98d0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
98e0: 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a .xClose method.*
98f0: 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 * may be invoked
9900: 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71 even if the [sq
9910: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d lite3_vfs.xOpen]
9920: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 reported that i
9930: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a t failed. The.*
9940: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 * only way to pr
9950: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 event a call to
9960: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 xClose following
9970: 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 a failed [sqlit
9980: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a e3_vfs.xOpen].**
9990: 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c is for the [sql
99a0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 ite3_vfs.xOpen]
99b0: 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 to set the sqlit
99c0: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 e3_file.pMethods
99d0: 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e element.** to N
99e0: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 ULL..**.** The f
99f0: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f lags argument to
9a00: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e xSync may be on
9a10: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e e of [SQLITE_SYN
9a20: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 C_NORMAL] or.**
9a30: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c [SQLITE_SYNC_FUL
9a40: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 L]. The first c
9a50: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 hoice is the nor
9a60: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 mal fsync()..**
9a70: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 The second choic
9a80: 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 e is a Mac OS X
9a90: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 style fullsync.
9aa0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e The [SQLITE_SYN
9ab0: 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 C_DATAONLY].** f
9ac0: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 lag may be ORed
9ad0: 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 in to indicate t
9ae0: 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 hat only the dat
9af0: 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a a of the file.**
9b00: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f and not its ino
9b10: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 de needs to be s
9b20: 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ynced..**.** The
9b30: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 integer values
9b40: 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 to xLock() and x
9b50: 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 Unlock() are one
9b60: 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c of.** <ul>.** <
9b70: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b li> [SQLITE_LOCK
9b80: 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 _NONE],.** <li>
9b90: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 [SQLITE_LOCK_SHA
9ba0: 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 RED],.** <li> [S
9bb0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 QLITE_LOCK_RESER
9bc0: 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 VED],.** <li> [S
9bd0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 QLITE_LOCK_PENDI
9be0: 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 NG], or.** <li>
9bf0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 [SQLITE_LOCK_EXC
9c00: 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c LUSIVE]..** </ul
9c10: 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 >.** xLock() inc
9c20: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e reases the lock.
9c30: 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 xUnlock() decre
9c40: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a ases the lock..*
9c50: 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 * The xCheckRese
9c60: 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f rvedLock() metho
9c70: 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 d checks whether
9c80: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f any database co
9c90: 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 nnection,.** eit
9ca0: 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 her in this proc
9cb0: 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f ess or in some o
9cc0: 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 ther process, is
9cd0: 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 holding a RESER
9ce0: 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c VED,.** PENDING,
9cf0: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f or EXCLUSIVE lo
9d00: 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 ck on the file.
9d10: 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 It returns true
9d20: 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f .** if such a lo
9d30: 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 ck exists and fa
9d40: 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a lse otherwise..*
9d50: 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f *.** The xFileCo
9d60: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 ntrol() method i
9d70: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 s a generic inte
9d80: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 rface that allow
9d90: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 s custom.** VFS
9da0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
9db0: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 to directly cont
9dc0: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 rol an open file
9dd0: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 using the.** [s
9de0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 qlite3_file_cont
9df0: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 rol()] interface
9e00: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f . The second "o
9e10: 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 p" argument is a
9e20: 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 n.** integer opc
9e30: 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 ode. The third
9e40: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 argument is a ge
9e50: 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e neric pointer in
9e60: 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 tended to.** poi
9e70: 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 nt to a structur
9e80: 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 e that may conta
9e90: 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 in arguments or
9ea0: 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 space in which t
9eb0: 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 o.** write retur
9ec0: 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e n values. Poten
9ed0: 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 tial uses for xF
9ee0: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 ileControl() mig
9ef0: 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f ht be.** functio
9f00: 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f ns to enable blo
9f10: 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 cking locks with
9f20: 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 timeouts, to ch
9f30: 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b ange the.** lock
9f40: 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f ing strategy (fo
9f50: 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 r example to use
9f60: 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 dot-file locks)
9f70: 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 , to inquire.**
9f80: 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 about the status
9f90: 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 of a lock, or t
9fa0: 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f o break stale lo
9fb0: 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 cks. The SQLite
9fc0: 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 .** core reserve
9fd0: 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 s all opcodes le
9fe0: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 ss than 100 for
9ff0: 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 its own use..**
a000: 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 A [file control
a010: 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f opcodes | list o
a020: 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 f opcodes] less
a030: 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 than 100 is avai
a040: 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 lable..** Applic
a050: 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 ations that defi
a060: 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c ne a custom xFil
a070: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 eControl method
a080: 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 should use opcod
a090: 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 es.** greater th
a0a0: 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 an 100 to avoid
a0b0: 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20 conflicts. VFS
a0c0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
a0d0: 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e should.** return
a0e0: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e [SQLITE_NOTFOUN
a0f0: 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 D] for file cont
a100: 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74 rol opcodes that
a110: 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 they do not.**
a120: 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a recognize..**.**
a130: 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 The xSectorSize
a140: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e () method return
a150: 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a s the sector siz
a160: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 e of the.** devi
a170: 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 ce that underlie
a180: 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 s the file. The
a190: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 sector size is
a1a0: 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 the.** minimum w
a1b0: 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 rite that can be
a1c0: 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f performed witho
a1d0: 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a ut disturbing.**
a1e0: 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 other bytes in
a1f0: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 the file. The x
a200: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 DeviceCharacteri
a210: 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f stics().** metho
a220: 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 d returns a bit
a230: 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e vector describin
a240: 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 g behaviors of t
a250: 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 he.** underlying
a260: 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c device:.**.** <
a270: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c ul>.** <li> [SQL
a280: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
a290: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
a2a0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 E_IOCAP_ATOMIC51
a2b0: 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 2].** <li> [SQLI
a2c0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 TE_IOCAP_ATOMIC1
a2d0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
a2e0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 TE_IOCAP_ATOMIC2
a2f0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
a300: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 TE_IOCAP_ATOMIC4
a310: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
a320: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 TE_IOCAP_ATOMIC8
a330: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
a340: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 TE_IOCAP_ATOMIC1
a350: 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 6K].** <li> [SQL
a360: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
a370: 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 32K].** <li> [SQ
a380: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
a390: 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 C64K].** <li> [S
a3a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 QLITE_IOCAP_SAFE
a3b0: 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e _APPEND].** <li>
a3c0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 [SQLITE_IOCAP_S
a3d0: 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f EQUENTIAL].** </
a3e0: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 ul>.**.** The SQ
a3f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
a400: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 C property means
a410: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 that all writes
a420: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 of.** any size
a430: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 are atomic. The
a440: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
a450: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a OMICnnn values.*
a460: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 * mean that writ
a470: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 es of blocks tha
a480: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 t are nnn bytes
a490: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 in size and.** a
a4a0: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e re aligned to an
a4b0: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 address which i
a4c0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c s an integer mul
a4d0: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 tiple of.** nnn
a4e0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 are atomic. The
a4f0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 SQLITE_IOCAP_SA
a500: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 FE_APPEND value
a510: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 means.** that wh
a520: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e en data is appen
a530: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 ded to a file, t
a540: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e he data is appen
a550: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 ded.** first the
a560: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 n the size of th
a570: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 e file is extend
a580: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 ed, never the ot
a590: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e her.** way aroun
a5a0: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 d. The SQLITE_I
a5b0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 OCAP_SEQUENTIAL
a5c0: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 property means t
a5d0: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 hat.** informati
a5e0: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f on is written to
a5f0: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d disk in the sam
a600: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 e order as calls
a610: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e .** to xWrite().
a620: 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 .**.** If xRead(
a630: 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 ) returns SQLITE
a640: 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 _IOERR_SHORT_REA
a650: 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 D it must also f
a660: 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e ill.** in the un
a670: 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 read portions of
a680: 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68 the buffer with
a690: 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 zeros. A VFS t
a6a0: 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 hat.** fails to
a6b0: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 zero-fill short
a6c0: 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d reads might seem
a6d0: 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 to work. Howev
a6e0: 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 er,.** failure t
a6f0: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 o zero-fill shor
a700: 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 t reads will eve
a710: 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a ntually lead to.
a720: 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 ** database corr
a730: 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 uption..*/.typed
a740: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
a750: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 3_io_methods sql
a760: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b ite3_io_methods;
a770: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f .struct sqlite3_
a780: 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 io_methods {. i
a790: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 nt iVersion;. i
a7a0: 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c nt (*xClose)(sql
a7b0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 ite3_file*);. i
a7c0: 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 nt (*xRead)(sqli
a7d0: 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a te3_file*, void*
a7e0: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 , int iAmt, sqli
a7f0: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 te3_int64 iOfst)
a800: 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 ;. int (*xWrite
a810: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
a820: 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e const void*, in
a830: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f t iAmt, sqlite3_
a840: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 int64 iOfst);.
a850: 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 int (*xTruncate)
a860: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
a870: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 sqlite3_int64 si
a880: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 ze);. int (*xSy
a890: 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 nc)(sqlite3_file
a8a0: 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 *, int flags);.
a8b0: 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 int (*xFileSize
a8c0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
a8d0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a sqlite3_int64 *
a8e0: 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a pSize);. int (*
a8f0: 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 xLock)(sqlite3_f
a900: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e ile*, int);. in
a910: 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c t (*xUnlock)(sql
a920: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 ite3_file*, int)
a930: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b ;. int (*xCheck
a940: 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 ReservedLock)(sq
a950: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 lite3_file*, int
a960: 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e *pResOut);. in
a970: 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c t (*xFileControl
a980: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
a990: 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 int op, void *p
a9a0: 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 Arg);. int (*xS
a9b0: 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 ectorSize)(sqlit
a9c0: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 e3_file*);. int
a9d0: 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 (*xDeviceCharac
a9e0: 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 teristics)(sqlit
a9f0: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 e3_file*);. /*
aa00: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 Methods above ar
aa10: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 e valid for vers
aa20: 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 ion 1 */. int (
aa30: 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 *xShmMap)(sqlite
aa40: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 3_file*, int iPg
aa50: 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c , int pgsz, int,
aa60: 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a void volatile**
aa70: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c );. int (*xShmL
aa80: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ock)(sqlite3_fil
aa90: 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 e*, int offset,
aaa0: 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 int n, int flags
aab0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d );. void (*xShm
aac0: 42 61 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 Barrier)(sqlite3
aad0: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 _file*);. int (
aae0: 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 *xShmUnmap)(sqli
aaf0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 te3_file*, int d
ab00: 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a eleteFlag);. /*
ab10: 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 Methods above a
ab20: 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 re valid for ver
ab30: 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 sion 2 */. int
ab40: 28 2a 78 46 65 74 63 68 29 28 73 71 6c 69 74 65 (*xFetch)(sqlite
ab50: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 3_file*, sqlite3
ab60: 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e _int64 iOfst, in
ab70: 74 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 t iAmt, void **p
ab80: 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 p);. int (*xUnf
ab90: 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 etch)(sqlite3_fi
aba0: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 le*, sqlite3_int
abb0: 36 34 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 64 iOfst, void *
abc0: 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 p);. /* Methods
abd0: 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 above are valid
abe0: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a for version 3 *
abf0: 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 /. /* Additiona
ac00: 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 l methods may be
ac10: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 added in future
ac20: 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a releases */.};.
ac30: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
ac40: 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 Standard File C
ac50: 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a ontrol Opcodes.*
ac60: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c * KEYWORDS: {fil
ac70: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 e control opcode
ac80: 73 7d 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c s} {file control
ac90: 20 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 opcode}.**.** T
aca0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e hese integer con
acb0: 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 stants are opcod
acc0: 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 es for the xFile
acd0: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a Control method.*
ace0: 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 * of the [sqlite
acf0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 3_io_methods] ob
ad00: 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 ject and for the
ad10: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 [sqlite3_file_c
ad20: 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 ontrol()].** int
ad30: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 erface..**.** <u
ad40: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 l>.** <li>[[SQLI
ad50: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 TE_FCNTL_LOCKSTA
ad60: 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c TE]].** The [SQL
ad70: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 ITE_FCNTL_LOCKST
ad80: 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 ATE] opcode is u
ad90: 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e sed for debuggin
ada0: 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f g. This.** opco
adb0: 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 de causes the xF
adc0: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f ileControl metho
add0: 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 d to write the c
ade0: 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a urrent state of.
adf0: 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 ** the lock (one
ae00: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b of [SQLITE_LOCK
ae10: 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f _NONE], [SQLITE_
ae20: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a LOCK_SHARED],.**
ae30: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 [SQLITE_LOCK_RE
ae40: 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 SERVED], [SQLITE
ae50: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 _LOCK_PENDING],
ae60: 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f or [SQLITE_LOCK_
ae70: 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 EXCLUSIVE]).** i
ae80: 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 nto an integer t
ae90: 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67 hat the pArg arg
aea0: 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e ument points to.
aeb0: 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 This capability
aec0: 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 .** is used duri
aed0: 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 69 ng testing and i
aee0: 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 s only available
aef0: 20 77 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 when the SQLITE
af00: 5f 54 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 _TEST.** compile
af10: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 -time option is
af20: 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e used..**.** <li>
af30: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 [[SQLITE_FCNTL_S
af40: 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 IZE_HINT]].** Th
af50: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
af60: 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 SIZE_HINT] opcod
af70: 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c e is used by SQL
af80: 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 ite to give the
af90: 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 VFS.** layer a h
afa0: 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 int of how large
afb0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
afc0: 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 le will grow to
afd0: 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a be during the.**
afe0: 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 current transac
aff0: 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 tion. This hint
b000: 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 is not guarante
b010: 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 ed to be accurat
b020: 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f e but it.** is o
b030: 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 ften close. The
b040: 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 underlying VFS
b050: 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 might choose to
b060: 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 preallocate data
b070: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 base.** file spa
b080: 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 ce based on this
b090: 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 hint in order t
b0a0: 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f o help writes to
b0b0: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a the database.**
b0c0: 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 file run faster
b0d0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
b0e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b LITE_FCNTL_CHUNK
b0f0: 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b _SIZE]].** The [
b100: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 SQLITE_FCNTL_CHU
b110: 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 NK_SIZE] opcode
b120: 69 73 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 is used to reque
b130: 73 74 20 74 68 61 74 20 74 68 65 20 56 46 53 0a st that the VFS.
b140: 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 ** extends and t
b150: 72 75 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 runcates the dat
b160: 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 abase file in ch
b170: 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 unks of a size s
b180: 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 pecified.** by t
b190: 68 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 he user. The fou
b1a0: 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rth argument to
b1b0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f [sqlite3_file_co
b1c0: 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 ntrol()] should
b1d0: 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 .** point to an
b1e0: 69 6e 74 65 67 65 72 20 28 74 79 70 65 20 69 6e integer (type in
b1f0: 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 t) containing th
b200: 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 e new chunk-size
b210: 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 to use.** for t
b220: 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 he nominated dat
b230: 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e abase. Allocatin
b240: 67 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 g database file
b250: 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a space in large.*
b260: 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d * chunks (say 1M
b270: 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 B at a time), ma
b280: 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 y reduce file-sy
b290: 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 stem fragmentati
b2a0: 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 on and.** improv
b2b0: 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e e performance on
b2c0: 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a some systems..*
b2d0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
b2e0: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 E_FCNTL_FILE_POI
b2f0: 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 NTER]].** The [S
b300: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 QLITE_FCNTL_FILE
b310: 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 _POINTER] opcode
b320: 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 is used to obta
b330: 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 in a pointer.**
b340: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
b350: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 file] object ass
b360: 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70 ociated with a p
b370: 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 articular databa
b380: 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e se.** connection
b390: 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69 . See the [sqli
b3a0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
b3b0: 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f ()] documentatio
b3c0: 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f n for.** additio
b3d0: 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e nal information.
b3e0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
b3f0: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f ITE_FCNTL_SYNC_O
b400: 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c MITTED]].** No l
b410: 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a onger in use..**
b420: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
b430: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a _FCNTL_SYNC]].**
b440: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e The [SQLITE_FCN
b450: 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20 TL_SYNC] opcode
b460: 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 is generated int
b470: 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 ernally by SQLit
b480: 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f e and.** sent to
b490: 20 74 68 65 20 56 46 53 20 69 6d 6d 65 64 69 61 the VFS immedia
b4a0: 74 65 6c 79 20 62 65 66 6f 72 65 20 74 68 65 20 tely before the
b4b0: 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 xSync method is
b4c0: 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 invoked on a.**
b4d0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 64 65 database file de
b4e0: 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66 scriptor. Or, if
b4f0: 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f the xSync metho
b500: 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 d is not invoked
b510: 20 0a 2a 2a 20 62 65 63 61 75 73 65 20 74 68 65 .** because the
b520: 20 75 73 65 72 20 68 61 73 20 63 6f 6e 66 69 67 user has config
b530: 75 72 65 64 20 53 51 4c 69 74 65 20 77 69 74 68 ured SQLite with
b540: 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e .** [PRAGMA syn
b550: 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d chronous | PRAGM
b560: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 A synchronous=OF
b570: 46 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 F] it is invoked
b580: 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 in place .** of
b590: 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f the xSync metho
b5a0: 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73 65 73 d. In most cases
b5b0: 2c 20 74 68 65 20 70 6f 69 6e 74 65 72 20 61 72 , the pointer ar
b5c0: 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 77 69 gument passed wi
b5d0: 74 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d th.** this file-
b5e0: 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e control is NULL.
b5f0: 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68 65 However, if the
b600: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 database file i
b610: 73 20 62 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a s being synced.*
b620: 2a 20 61 73 20 70 61 72 74 20 6f 66 20 61 20 6d * as part of a m
b630: 75 6c 74 69 2d 64 61 74 61 62 61 73 65 20 63 6f ulti-database co
b640: 6d 6d 69 74 2c 20 74 68 65 20 61 72 67 75 6d 65 mmit, the argume
b650: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e nt points to a n
b660: 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a ul-terminated.**
b670: 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 string containi
b680: 6e 67 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 ng the transacti
b690: 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e ons master-journ
b6a0: 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46 al file name. VF
b6b0: 53 65 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20 Ses that .** do
b6c0: 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 not need this si
b6d0: 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65 gnal should sile
b6e0: 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 ntly ignore this
b6f0: 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 opcode. Applica
b700: 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 tions .** should
b710: 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 not call [sqlit
b720: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 e3_file_control(
b730: 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 )] with this opc
b740: 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 ode as doing so
b750: 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75 70 74 20 may .** disrupt
b760: 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 the operation of
b770: 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 the specialized
b780: 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 VFSes that do r
b790: 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a equire it. .**.
b7a0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
b7b0: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 FCNTL_COMMIT_PHA
b7c0: 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b SETWO]].** The [
b7d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d SQLITE_FCNTL_COM
b7e0: 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70 MIT_PHASETWO] op
b7f0: 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 code is generate
b800: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 d internally by
b810: 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65 SQLite.** and se
b820: 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 61 66 nt to the VFS af
b830: 74 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f ter a transactio
b840: 6e 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69 n has been commi
b850: 74 74 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 tted immediately
b860: 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72 65 20 74 .** but before t
b870: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 75 he database is u
b880: 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73 20 74 nlocked. VFSes t
b890: 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 hat do not need
b8a0: 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 this signal.** s
b8b0: 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 hould silently i
b8c0: 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 gnore this opcod
b8d0: 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 e. Applications
b8e0: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a should not call.
b8f0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 ** [sqlite3_file
b900: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 _control()] with
b910: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 this opcode as
b920: 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 doing so may dis
b930: 72 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65 rupt the .** ope
b940: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 ration of the sp
b950: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 ecialized VFSes
b960: 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 that do require
b970: 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e it. .**.** <li>
b980: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 [[SQLITE_FCNTL_W
b990: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a IN32_AV_RETRY]].
b9a0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f ** ^The [SQLITE_
b9b0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 FCNTL_WIN32_AV_R
b9c0: 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 ETRY] opcode is
b9d0: 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 used to configur
b9e0: 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 e automatic.** r
b9f0: 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 etry counts and
ba00: 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 intervals for ce
ba10: 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f rtain disk I/O o
ba20: 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 perations for th
ba30: 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 e.** windows [VF
ba40: 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 S] in order to p
ba50: 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 rovide robustnes
ba60: 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63 s in the presenc
ba70: 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 e of.** anti-vir
ba80: 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 us programs. By
ba90: 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 default, the wi
baa0: 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 ndows VFS will r
bab0: 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a etry file read,.
bac0: 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 ** file write, a
bad0: 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f nd file delete o
bae0: 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 perations up to
baf0: 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61 10 times, with a
bb00: 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 delay.** of 25
bb10: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 milliseconds bef
bb20: 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 72 65 ore the first re
bb30: 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 68 65 try and with the
bb40: 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e delay increasin
bb50: 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74 g.** by an addit
bb60: 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 ional 25 millise
bb70: 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68 20 conds with each
bb80: 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 72 79 subsequent retry
bb90: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 . This.** opcod
bba0: 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 e allows these t
bbb0: 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72 65 wo values (10 re
bbc0: 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c tries and 25 mil
bbd0: 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c liseconds of del
bbe0: 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a ay).** to be adj
bbf0: 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75 usted. The valu
bc00: 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 20 66 es are changed f
bc10: 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 or all database
bc20: 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 connections.** w
bc30: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 ithin the same p
bc40: 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72 67 rocess. The arg
bc50: 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 ument is a point
bc60: 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f er to an array o
bc70: 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 f two.** integer
bc80: 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73 s where the firs
bc90: 74 20 69 6e 74 65 67 65 72 20 69 20 74 68 65 20 t integer i the
bca0: 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20 new retry count
bcb0: 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a and the second.*
bcc0: 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 * integer is the
bcd0: 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68 delay. If eith
bce0: 65 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65 er integer is ne
bcf0: 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 gative, then the
bd00: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e setting.** is n
bd10: 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 69 ot changed but i
bd20: 6e 73 74 65 61 64 20 74 68 65 20 70 72 69 6f 72 nstead the prior
bd30: 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73 value of that s
bd40: 65 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 65 etting is writte
bd50: 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 n.** into the ar
bd60: 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 ray entry, allow
bd70: 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 20 ing the current
bd80: 72 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 74 retry settings t
bd90: 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 o be.** interrog
bda0: 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 ated. The zDbNa
bdb0: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 me parameter is
bdc0: 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c ignored..**.** <
bdd0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
bde0: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a L_PERSIST_WAL]].
bdf0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f ** ^The [SQLITE_
be00: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 FCNTL_PERSIST_WA
be10: 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 L] opcode is use
be20: 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 d to set or quer
be30: 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 y the.** persist
be40: 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 ent [WAL | Write
be50: 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 Ahead Log] sett
be60: 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 ing. By default
be70: 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a , the auxiliary.
be80: 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 6c ** write ahead l
be90: 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 og and shared me
bea0: 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64 20 mory files used
beb0: 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 for transaction
bec0: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 control.** are a
bed0: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c utomatically del
bee0: 65 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 eted when the la
bef0: 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 test connection
bf00: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a to the database.
bf10: 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 ** closes. Sett
bf20: 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 ing persistent W
bf30: 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 AL mode causes t
bf40: 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 hose files to pe
bf50: 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 rsist after.** c
bf60: 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e lose. Persistin
bf70: 67 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 g the files is u
bf80: 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 seful when other
bf90: 20 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 processes that
bfa0: 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 do not.** have w
bfb0: 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 rite permission
bfc0: 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 on the directory
bfd0: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 containing the
bfe0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 database file wa
bff0: 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 nt.** to read th
c000: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c e database file,
c010: 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 as the WAL and
c020: 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 shared memory fi
c030: 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a les must exist.*
c040: 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 * in order for t
c050: 68 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 he database to b
c060: 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 e readable. The
c070: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
c080: 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 r to.** [sqlite3
c090: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d _file_control()]
c0a0: 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 for this opcode
c0b0: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 should be a poi
c0c0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 nter to an integ
c0d0: 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 er..** That inte
c0e0: 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 ger is 0 to disa
c0f0: 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 ble persistent W
c100: 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 AL mode or 1 to
c110: 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e enable persisten
c120: 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 t.** WAL mode.
c130: 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 If the integer i
c140: 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 s -1, then it is
c150: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 overwritten wit
c160: 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a h the current.**
c170: 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 WAL persistence
c180: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 setting..**.**
c190: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
c1a0: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 TL_POWERSAFE_OVE
c1b0: 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 RWRITE]].** ^The
c1c0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 [SQLITE_FCNTL_P
c1d0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 OWERSAFE_OVERWRI
c1e0: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 TE] opcode is us
c1f0: 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 ed to set or que
c200: 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 ry the.** persis
c210: 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d tent "powersafe-
c220: 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 50 overwrite" or "P
c230: 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54 SOW" setting. T
c240: 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a he PSOW setting.
c250: 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 ** determines th
c260: 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f e [SQLITE_IOCAP_
c270: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 POWERSAFE_OVERWR
c280: 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a ITE] bit of the.
c290: 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 63 ** xDeviceCharac
c2a0: 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 teristics method
c2b0: 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 s. The fourth pa
c2c0: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 rameter to.** [s
c2d0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 qlite3_file_cont
c2e0: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 rol()] for this
c2f0: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 opcode should be
c300: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
c310: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 integer..** Tha
c320: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 t integer is 0 t
c330: 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 o disable zero-d
c340: 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 amage mode or 1
c350: 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 to enable zero-d
c360: 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 amage.** 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 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 zero-damage mod
c3c0: 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a e setting..**.**
c3d0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
c3e0: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a NTL_OVERWRITE]].
c3f0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f ** ^The [SQLITE_
c400: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d FCNTL_OVERWRITE]
c410: 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b opcode is invok
c420: 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 ed by SQLite aft
c430: 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 er opening.** a
c440: 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f write transactio
c450: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 n to indicate th
c460: 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 at, unless it is
c470: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 rolled back for
c480: 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c some.** reason,
c490: 20 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 the entire data
c4a0: 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 base file will b
c4b0: 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 e overwritten by
c4c0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a the current .**
c4d0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 transaction. Th
c4e0: 69 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41 is is used by VA
c4f0: 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e CUUM operations.
c500: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
c510: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d ITE_FCNTL_VFSNAM
c520: 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c E]].** ^The [SQL
c530: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d ITE_FCNTL_VFSNAM
c540: 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 E] opcode can be
c550: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 used to obtain
c560: 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 the names of.**
c570: 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 all [VFSes] in t
c580: 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 he VFS stack. T
c590: 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 he names are of
c5a0: 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e all VFS shims an
c5b0: 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 d the.** final b
c5c0: 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 ottom-level VFS
c5d0: 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f are written into
c5e0: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 memory obtained
c5f0: 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 from .** [sqlit
c600: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 e3_malloc()] and
c610: 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 the result is s
c620: 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 tored in the cha
c630: 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 r* variable.** t
c640: 68 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 hat the fourth p
c650: 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c arameter of [sql
c660: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
c670: 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a l()] points to..
c680: 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 ** The caller is
c690: 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 responsible for
c6a0: 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d freeing the mem
c6b0: 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 ory when done.
c6c0: 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 As with.** all f
c6d0: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 ile-control acti
c6e0: 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f ons, there is no
c6f0: 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 guarantee that
c700: 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c this will actual
c710: 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e ly.** do anythin
c720: 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 g. Callers shou
c730: 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 ld initialize th
c740: 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 e char* variable
c750: 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f to a NULL.** po
c760: 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 inter in case th
c770: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 is file-control
c780: 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 is not implement
c790: 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 ed. This file-c
c7a0: 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 ontrol.** is int
c7b0: 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f ended for diagno
c7c0: 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a stic use only..*
c7d0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
c7e0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d E_FCNTL_PRAGMA]]
c7f0: 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20 .** ^Whenever a
c800: 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 [PRAGMA] stateme
c810: 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e nt is parsed, an
c820: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 [SQLITE_FCNTL_P
c830: 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 RAGMA] .** file
c840: 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 control is sent
c850: 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c to the open [sql
c860: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 ite3_file] objec
c870: 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a t corresponding.
c880: 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 ** to the databa
c890: 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68 se file to which
c8a0: 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 74 the pragma stat
c8b0: 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 ement refers. ^T
c8c0: 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 he argument.** t
c8d0: 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 o the [SQLITE_FC
c8e0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 NTL_PRAGMA] file
c8f0: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 control is an a
c900: 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 rray of.** point
c910: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28 ers to strings (
c920: 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 char**) in which
c930: 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d the second elem
c940: 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 79 ent of the array
c950: 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 .** is the name
c960: 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e of the pragma an
c970: 64 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d d the third elem
c980: 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 6d ent is the argum
c990: 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 ent to the.** pr
c9a0: 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 agma or NULL if
c9b0: 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e the pragma has n
c9c0: 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 o argument. ^Th
c9d0: 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e e handler for an
c9e0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 .** [SQLITE_FCNT
c9f0: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 L_PRAGMA] file c
ca00: 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f ontrol can optio
ca10: 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 nally make the f
ca20: 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 irst element.**
ca30: 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72 of the char** ar
ca40: 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 gument point to
ca50: 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 a string obtaine
ca60: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f d from [sqlite3_
ca70: 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 mprintf()].** or
ca80: 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 the equivalent
ca90: 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 20 and that string
caa0: 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 will become the
cab0: 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72 result of the pr
cac0: 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 agma or.** the e
cad0: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20 rror message if
cae0: 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73 the pragma fails
caf0: 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 . ^If the.** [SQ
cb00: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d LITE_FCNTL_PRAGM
cb10: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 A] file control
cb20: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
cb30: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 NOTFOUND], then
cb40: 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 normal .** [PRAG
cb50: 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63 MA] processing c
cb60: 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 ontinues. ^If t
cb70: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
cb80: 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 _PRAGMA].** file
cb90: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 control returns
cba0: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 [SQLITE_OK], th
cbb0: 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 73 en the parser as
cbc0: 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a sumes that the.*
cbd0: 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65 * VFS has handle
cbe0: 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 73 d the PRAGMA its
cbf0: 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 73 elf and the pars
cc00: 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e er generates a n
cc10: 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 o-op.** prepared
cc20: 20 73 74 61 74 65 6d 65 6e 74 20 69 66 20 72 65 statement if re
cc30: 73 75 6c 74 20 73 74 72 69 6e 67 20 69 73 20 4e sult string is N
cc40: 55 4c 4c 2c 20 6f 72 20 74 68 61 74 20 72 65 74 ULL, or that ret
cc50: 75 72 6e 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f urns a copy.** o
cc60: 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 74 72 f the result str
cc70: 69 6e 67 20 69 66 20 74 68 65 20 73 74 72 69 6e ing if the strin
cc80: 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a g is non-NULL..*
cc90: 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 * ^If the [SQLIT
cca0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 E_FCNTL_PRAGMA]
ccb0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 file control ret
ccc0: 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 urns.** any resu
ccd0: 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68 lt code other th
cce0: 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f an [SQLITE_OK] o
ccf0: 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 r [SQLITE_NOTFOU
cd00: 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a ND], that means.
cd10: 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53 20 ** that the VFS
cd20: 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 encountered an e
cd30: 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c rror while handl
cd40: 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d ing the [PRAGMA]
cd50: 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 and the.** comp
cd60: 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 ilation of the P
cd70: 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68 RAGMA fails with
cd80: 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 an error. ^The
cd90: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 [SQLITE_FCNTL_P
cda0: 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 RAGMA].** file c
cdb0: 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 ontrol occurs at
cdc0: 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f the beginning o
cdd0: 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 f pragma stateme
cde0: 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 nt analysis and
cdf0: 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 so.** it is able
ce00: 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69 to override bui
ce10: 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 lt-in [PRAGMA] s
ce20: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a tatements..**.**
ce30: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
ce40: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d NTL_BUSYHANDLER]
ce50: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 ].** ^The [SQLIT
ce60: 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 E_FCNTL_BUSYHAND
ce70: 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e LER].** file-con
ce80: 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f trol may be invo
ce90: 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e ked by SQLite on
cea0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
ceb0: 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f le handle.** sho
cec0: 72 74 6c 79 20 61 66 74 65 72 20 69 74 20 69 73 rtly after it is
ced0: 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 opened in order
cee0: 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75 to provide a cu
cef0: 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63 stom VFS with ac
cf00: 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 cess.** to the c
cf10: 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d onnections busy-
cf20: 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b handler callback
cf30: 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 . The argument i
cf40: 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20 s of type (void
cf50: 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 **).** - an arra
cf60: 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a y of two (void *
cf70: 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69 ) values. The fi
cf80: 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74 rst (void *) act
cf90: 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 ually points.**
cfa0: 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 to a function of
cfb0: 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76 type (int (*)(v
cfc0: 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 oid *)). In orde
cfd0: 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 r to invoke the
cfe0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 connections.** b
cff0: 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 usy-handler, thi
d000: 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c s function shoul
d010: 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 d be invoked wit
d020: 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f h the second (vo
d030: 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 id *) in.** the
d040: 61 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c array as the onl
d050: 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 y argument. If i
d060: 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 t returns non-ze
d070: 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65 ro, then the ope
d080: 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 ration.** should
d090: 20 62 65 20 72 65 74 72 69 65 64 2e 20 49 66 20 be retried. If
d0a0: 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c it returns zero,
d0b0: 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20 the custom VFS
d0c0: 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 should abandon t
d0d0: 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 he.** current op
d0e0: 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c eration..**.** <
d0f0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
d100: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d L_TEMPFILENAME]]
d110: 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e .** ^Application
d120: 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 can invoke the
d130: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 [SQLITE_FCNTL_TE
d140: 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 MPFILENAME] file
d150: 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 -control.** to h
d160: 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72 ave SQLite gener
d170: 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 ate a.** tempora
d180: 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e ry filename usin
d190: 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 g the same algor
d1a0: 69 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c ithm that is fol
d1b0: 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74 lowed to generat
d1c0: 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 e.** temporary f
d1d0: 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d ilenames for TEM
d1e0: 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 P tables and oth
d1f0: 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 er internal uses
d200: 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 . The.** argume
d210: 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 nt should be a c
d220: 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c har** which will
d230: 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20 be filled with
d240: 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 the filename.**
d250: 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d written into mem
d260: 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f ory obtained fro
d270: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f m [sqlite3_mallo
d280: 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 c()]. The calle
d290: 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f r should.** invo
d2a0: 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ke [sqlite3_free
d2b0: 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c ()] on the resul
d2c0: 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d t to avoid a mem
d2d0: 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 ory leak..**.**
d2e0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
d2f0: 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a TL_MMAP_SIZE]].*
d300: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 * The [SQLITE_FC
d310: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 NTL_MMAP_SIZE] f
d320: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 ile control is u
d330: 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72 20 sed to query or
d340: 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d set the.** maxim
d350: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 um number of byt
d360: 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 es that will be
d370: 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d used for memory-
d380: 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 mapped I/O..** T
d390: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 he argument is a
d3a0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 pointer to a va
d3b0: 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69 lue of type sqli
d3c0: 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a te3_int64 that.*
d3d0: 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72 79 * is an advisory
d3e0: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 maximum number
d3f0: 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 of bytes in the
d400: 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d file to memory m
d410: 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e ap. The.** poin
d420: 74 65 72 20 69 73 20 6f 76 65 72 77 72 69 74 74 ter is overwritt
d430: 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64 20 en with the old
d440: 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 value. The limi
d450: 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 t is not changed
d460: 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 if.** the value
d470: 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e originally poin
d480: 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69 ted to is negati
d490: 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 63 ve, and so the c
d4a0: 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a urrent limit .**
d4b0: 20 63 61 6e 20 62 65 20 71 75 65 72 69 65 64 20 can be queried
d4c0: 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61 20 by passing in a
d4d0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 pointer to a neg
d4e0: 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 ative number. T
d4f0: 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 his.** file-cont
d500: 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74 65 rol is used inte
d510: 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d rnally to implem
d520: 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 ent [PRAGMA mmap
d530: 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c _size]..**.** <l
d540: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
d550: 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 _TRACE]].** The
d560: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 [SQLITE_FCNTL_TR
d570: 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f ACE] file contro
d580: 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76 69 73 l provides advis
d590: 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a ory information.
d5a0: 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61 62 ** to the VFS ab
d5b0: 6f 75 74 20 77 68 61 74 20 74 68 65 20 68 69 67 out what the hig
d5c0: 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74 68 her layers of th
d5d0: 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 61 e SQLite stack a
d5e0: 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 re doing..** Thi
d5f0: 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 s file control i
d600: 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20 56 s used by some V
d610: 46 53 20 61 63 74 69 76 69 74 79 20 74 72 61 63 FS activity trac
d620: 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 ing [shims]..**
d630: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 The argument is
d640: 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 a zero-terminate
d650: 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68 65 d string. Highe
d660: 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65 0a r layers in the.
d670: 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 ** SQLite stack
d680: 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e 73 may generate ins
d690: 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20 66 tances of this f
d6a0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a ile control if.*
d6b0: 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 * the [SQLITE_US
d6c0: 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 E_FCNTL_TRACE] c
d6d0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
d6e0: 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a on is enabled..*
d6f0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
d700: 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 E_FCNTL_HAS_MOVE
d710: 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 D]].** The [SQLI
d720: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 TE_FCNTL_HAS_MOV
d730: 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c ED] file control
d740: 20 69 6e 74 65 72 70 72 65 74 73 20 69 74 73 20 interprets its
d750: 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a argument as a.**
d760: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
d770: 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20 77 72 nteger and it wr
d780: 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 ites a boolean i
d790: 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 nto that integer
d7a0: 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e depending.** on
d7b0: 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 whether or not
d7c0: 74 68 65 20 66 69 6c 65 20 68 61 73 20 62 65 65 the file has bee
d7d0: 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 n renamed, moved
d7e0: 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69 6e , or deleted sin
d7f0: 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 ce it.** was fir
d800: 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a st opened..**.**
d810: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
d820: 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 NTL_WIN32_SET_HA
d830: 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 NDLE]].** The [S
d840: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 QLITE_FCNTL_WIN3
d850: 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 2_SET_HANDLE] op
d860: 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 code is used for
d870: 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 debugging. Thi
d880: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 s.** opcode caus
d890: 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 es the xFileCont
d8a0: 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 rol method to sw
d8b0: 61 70 20 74 68 65 20 66 69 6c 65 20 68 61 6e 64 ap the file hand
d8c0: 6c 65 20 77 69 74 68 20 74 68 65 20 6f 6e 65 0a le with the one.
d8d0: 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 ** pointed to by
d8e0: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 the pArg argume
d8f0: 6e 74 2e 20 20 54 68 69 73 20 63 61 70 61 62 69 nt. This capabi
d900: 6c 69 74 79 20 69 73 20 75 73 65 64 20 64 75 72 lity is used dur
d910: 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 ing testing.** a
d920: 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f nd only needs to
d930: 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 be supported wh
d940: 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 20 69 en SQLITE_TEST i
d950: 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a s defined..**.**
d960: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
d970: 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a NTL_WAL_BLOCK]].
d980: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 ** The [SQLITE_F
d990: 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 CNTL_WAL_BLOCK]
d9a0: 69 73 20 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 is a signal to t
d9b0: 68 65 20 56 46 53 20 6c 61 79 65 72 20 74 68 61 he VFS layer tha
d9c0: 74 20 69 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 t it might.** be
d9d0: 20 61 64 76 61 6e 74 61 67 65 6f 75 73 20 74 6f advantageous to
d9e0: 20 62 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 block on the ne
d9f0: 78 74 20 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 xt WAL lock if t
da00: 68 65 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 he lock is not i
da10: 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 mmediately.** av
da20: 61 69 6c 61 62 6c 65 2e 20 20 54 68 65 20 57 41 ailable. The WA
da30: 4c 20 73 75 62 73 79 73 74 65 6d 20 69 73 73 75 L subsystem issu
da40: 65 73 20 74 68 69 73 20 73 69 67 6e 61 6c 20 64 es this signal d
da50: 75 72 69 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 uring rare.** ci
da60: 72 63 75 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f rcumstances in o
da70: 72 64 65 72 20 74 6f 20 66 69 78 20 61 20 70 72 rder to fix a pr
da80: 6f 62 6c 65 6d 20 77 69 74 68 20 70 72 69 6f 72 oblem with prior
da90: 69 74 79 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a ity inversion..*
daa0: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 * Applications s
dab0: 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 hould <em>not</e
dac0: 6d 3e 20 75 73 65 20 74 68 69 73 20 66 69 6c 65 m> use this file
dad0: 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 -control..**.**
dae0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
daf0: 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 TL_ZIPVFS]].** T
db00: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
db10: 5f 5a 49 50 56 46 53 5d 20 6f 70 63 6f 64 65 20 _ZIPVFS] opcode
db20: 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 is implemented b
db30: 79 20 7a 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41 y zipvfs only. A
db40: 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20 ll other.** VFS
db50: 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51 should return SQ
db60: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f LITE_NOTFOUND fo
db70: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a r this opcode..*
db80: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
db90: 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a E_FCNTL_RBU]].**
dba0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e The [SQLITE_FCN
dbb0: 54 4c 5f 52 42 55 5d 20 6f 70 63 6f 64 65 20 69 TL_RBU] opcode i
dbc0: 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 s implemented by
dbd0: 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 the special VFS
dbe0: 20 75 73 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 used by.** the
dbf0: 52 42 55 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e RBU extension on
dc00: 6c 79 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 56 ly. All other V
dc10: 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e FS should return
dc20: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 SQLITE_NOTFOUND
dc30: 20 66 6f 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63 for.** this opc
dc40: 6f 64 65 2e 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a ode. .** </ul>.
dc50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
dc60: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 E_FCNTL_LOCKSTAT
dc70: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 E
dc80: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
dc90: 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 _FCNTL_GET_LOCKP
dca0: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 32 ROXYFILE 2
dcb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
dcc0: 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 FCNTL_SET_LOCKPR
dcd0: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 33 0a OXYFILE 3.
dce0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
dcf0: 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 CNTL_LAST_ERRNO
dd00: 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 4.#
dd10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
dd20: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 NTL_SIZE_HINT
dd30: 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 5.#d
dd40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
dd50: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 TL_CHUNK_SIZE
dd60: 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 6.#de
dd70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
dd80: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 L_FILE_POINTER
dd90: 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 7.#def
dda0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
ddb0: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 _SYNC_OMITTED
ddc0: 20 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 8.#defi
ddd0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
dde0: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20 WIN32_AV_RETRY
ddf0: 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 9.#defin
de00: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 e SQLITE_FCNTL_P
de10: 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20 ERSIST_WAL
de20: 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 10.#define
de30: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 SQLITE_FCNTL_OV
de40: 45 52 57 52 49 54 45 20 20 20 20 20 20 20 20 20 ERWRITE
de50: 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 11.#define
de60: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 SQLITE_FCNTL_VFS
de70: 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 NAME
de80: 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 12.#define S
de90: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 QLITE_FCNTL_POWE
dea0: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 RSAFE_OVERWRITE
deb0: 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51 13.#define SQ
dec0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d LITE_FCNTL_PRAGM
ded0: 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 A
dee0: 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 14.#define SQL
def0: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 ITE_FCNTL_BUSYHA
df00: 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20 20 20 NDLER
df10: 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 15.#define SQLI
df20: 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c TE_FCNTL_TEMPFIL
df30: 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 ENAME
df40: 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 16.#define SQLIT
df50: 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a E_FCNTL_MMAP_SIZ
df60: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 E 1
df70: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 8.#define SQLITE
df80: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 _FCNTL_TRACE
df90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 19
dfa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
dfb0: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 FCNTL_HAS_MOVED
dfc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 0a 20.
dfd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
dfe0: 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20 20 20 20 CNTL_SYNC
dff0: 20 20 20 20 20 20 20 20 20 20 20 20 32 31 0a 23 21.#
e000: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
e010: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 NTL_COMMIT_PHASE
e020: 54 57 4f 20 20 20 20 20 20 20 20 32 32 0a 23 64 TWO 22.#d
e030: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
e040: 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e TL_WIN32_SET_HAN
e050: 44 4c 45 20 20 20 20 20 20 20 32 33 0a 23 64 65 DLE 23.#de
e060: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
e070: 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 L_WAL_BLOCK
e080: 20 20 20 20 20 20 20 20 20 32 34 0a 23 64 65 66 24.#def
e090: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
e0a0: 5f 5a 49 50 56 46 53 20 20 20 20 20 20 20 20 20 _ZIPVFS
e0b0: 20 20 20 20 20 20 20 20 32 35 0a 23 64 65 66 69 25.#defi
e0c0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
e0d0: 52 42 55 20 20 20 20 20 20 20 20 20 20 20 20 20 RBU
e0e0: 20 20 20 20 20 20 20 32 36 0a 0a 2f 2a 20 64 65 26../* de
e0f0: 70 72 65 63 61 74 65 64 20 6e 61 6d 65 73 20 2a precated names *
e100: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
e110: 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 _GET_LOCKPROXYFI
e120: 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 LE SQLITE_F
e130: 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f CNTL_GET_LOCKPRO
e140: 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 XYFILE.#define S
e150: 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 QLITE_SET_LOCKPR
e160: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c OXYFILE SQL
e170: 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f ITE_FCNTL_SET_LO
e180: 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 CKPROXYFILE.#def
e190: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f ine SQLITE_LAST_
e1a0: 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 ERRNO
e1b0: 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c SQLITE_FCNTL_L
e1c0: 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a AST_ERRNO.../*.*
e1d0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 * CAPI3REF: Mute
e1e0: 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 x Handle.**.** T
e1f0: 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 he mutex module
e200: 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 within SQLite de
e210: 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d fines [sqlite3_m
e220: 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a utex] to be an.*
e230: 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20 * abstract type
e240: 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 for a mutex obje
e250: 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 ct. The SQLite
e260: 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 core never looks
e270: 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 .** at the inter
e280: 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 nal representati
e290: 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 on of an [sqlite
e2a0: 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 3_mutex]. It on
e2b0: 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 ly.** deals with
e2c0: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 pointers to the
e2d0: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d [sqlite3_mutex]
e2e0: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d object..**.** M
e2f0: 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74 utexes are creat
e300: 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ed using [sqlite
e310: 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 3_mutex_alloc()]
e320: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
e330: 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 uct sqlite3_mute
e340: 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b x sqlite3_mutex;
e350: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
e360: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f : OS Interface O
e370: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 bject.**.** An i
e380: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 nstance of the s
e390: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 qlite3_vfs objec
e3a0: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e t defines the in
e3b0: 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a terface between.
e3c0: 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f ** the SQLite co
e3d0: 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 re and the under
e3e0: 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 lying operating
e3f0: 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 system. The "vf
e400: 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d s".** in the nam
e410: 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 e of the object
e420: 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 stands for "virt
e430: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 ual file system"
e440: 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 . See.** the [V
e450: 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e FS | VFS documen
e460: 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 tation] for furt
e470: 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e her information.
e480: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 .**.** The value
e490: 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e of the iVersion
e4a0: 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 field is initia
e4b0: 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 lly 1 but may be
e4c0: 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 larger in.** fu
e4d0: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 ture versions of
e4e0: 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 SQLite. Additi
e4f0: 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 onal fields may
e500: 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 be appended to t
e510: 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 his.** object wh
e520: 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 en the iVersion
e530: 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 value is increas
e540: 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 ed. Note that t
e550: 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 he structure.**
e560: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 of the sqlite3_v
e570: 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 fs object change
e580: 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 s in the transac
e590: 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 tion between.**
e5a0: 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 SQLite version 3
e5b0: 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 .5.9 and 3.6.0 a
e5c0: 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73 nd yet the iVers
e5d0: 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f ion field was no
e5e0: 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a t.** modified..*
e5f0: 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c *.** The szOsFil
e600: 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 e field is the s
e610: 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c ize of the subcl
e620: 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 assed [sqlite3_f
e630: 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 ile].** structur
e640: 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 e used by this V
e650: 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 FS. mxPathname
e660: 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c is the maximum l
e670: 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 ength of.** a pa
e680: 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 thname in this V
e690: 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 FS..**.** Regist
e6a0: 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 ered sqlite3_vfs
e6b0: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 objects are kep
e6c0: 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 t on a linked li
e6d0: 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 st formed by.**
e6e0: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 the pNext pointe
e6f0: 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 r. The [sqlite3
e700: 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d _vfs_register()]
e710: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 .** and [sqlite3
e720: 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 _vfs_unregister(
e730: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 )] interfaces ma
e740: 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a nage this list.*
e750: 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 * in a thread-sa
e760: 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 fe way. The [sq
e770: 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 lite3_vfs_find()
e780: 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 ] interface.** s
e790: 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 earches the list
e7a0: 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 . Neither the a
e7b0: 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 pplication code
e7c0: 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 nor the VFS.** i
e7d0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 mplementation sh
e7e0: 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 ould use the pNe
e7f0: 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a xt pointer..**.*
e800: 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c * The pNext fiel
e810: 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 d is the only fi
e820: 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 eld in the sqlit
e830: 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 e3_vfs.** struct
e840: 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 ure that SQLite
e850: 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 will ever modify
e860: 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f . SQLite will o
e870: 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 nly access.** or
e880: 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 modify this fie
e890: 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 ld while holding
e8a0: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 a particular st
e8b0: 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 atic mutex..** T
e8c0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 he application s
e8d0: 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 hould never modi
e8e0: 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 fy anything with
e8f0: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 in the sqlite3_v
e900: 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 fs.** object onc
e910: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 e the object has
e920: 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 been registered
e930: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d ..**.** The zNam
e940: 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 e field holds th
e950: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 e name of the VF
e960: 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e S module. The n
e970: 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 ame must.** be u
e980: 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c nique across all
e990: 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a VFS modules..**
e9a0: 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 .** [[sqlite3_vf
e9b0: 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 s.xOpen]].** ^SQ
e9c0: 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 Lite guarantees
e9d0: 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 that the zFilena
e9e0: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 me parameter to
e9f0: 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 xOpen.** is eith
ea00: 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 er a NULL pointe
ea10: 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 r or string obta
ea20: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 ined.** from xFu
ea30: 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 llPathname() wit
ea40: 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 h an optional su
ea50: 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e ffix added..** ^
ea60: 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20 61 If a suffix is a
ea70: 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c dded to the zFil
ea80: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c ename parameter,
ea90: 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 it will.** cons
eaa0: 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 ist of a single
eab0: 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 6f "-" character fo
eac0: 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 llowed by no mor
ead0: 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 e than.** 11 alp
eae0: 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 hanumeric and/or
eaf0: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e "-" characters.
eb00: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 .** ^SQLite furt
eb10: 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 her guarantees t
eb20: 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e hat.** the strin
eb30: 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 g will be valid
eb40: 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e and unchanged un
eb50: 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a til xClose() is.
eb60: 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 ** called. Becau
eb70: 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f se of the previo
eb80: 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 us sentence,.**
eb90: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c the [sqlite3_fil
eba0: 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 e] can safely st
ebb0: 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f ore a pointer to
ebc0: 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 the.** filename
ebd0: 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 if it needs to
ebe0: 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c remember the fil
ebf0: 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 ename for some r
ec00: 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 eason..** If the
ec10: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d zFilename param
ec20: 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 eter to xOpen is
ec30: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
ec40: 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 then xOpen.** mu
ec50: 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 st invent its ow
ec60: 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 n temporary name
ec70: 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 for the file.
ec80: 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a ^Whenever the .*
ec90: 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 * xFilename para
eca0: 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 meter is NULL it
ecb0: 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 will also be th
ecc0: 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a e case that the.
ecd0: 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 ** flags paramet
ece0: 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 er will include
ecf0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c [SQLITE_OPEN_DEL
ed00: 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a ETEONCLOSE]..**.
ed10: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 ** The flags arg
ed20: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 ument to xOpen()
ed30: 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 includes all bi
ed40: 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 ts set in.** the
ed50: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 flags argument
ed60: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e to [sqlite3_open
ed70: 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b _v2()]. Or if [
ed80: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a sqlite3_open()].
ed90: 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f ** or [sqlite3_o
eda0: 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 pen16()] is used
edb0: 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 , then flags inc
edc0: 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a ludes at least.*
edd0: 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 * [SQLITE_OPEN_R
ede0: 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c EADWRITE] | [SQL
edf0: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d ITE_OPEN_CREATE]
ee00: 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 . .** If xOpen()
ee10: 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 opens a file re
ee20: 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 ad-only then it
ee30: 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 sets *pOutFlags
ee40: 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 to.** include [S
ee50: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f QLITE_OPEN_READO
ee60: 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 NLY]. Other bit
ee70: 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 s in *pOutFlags
ee80: 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a may be set..**.*
ee90: 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 * ^(SQLite will
eea0: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 also add one of
eeb0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c the following fl
eec0: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e ags to the xOpen
eed0: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 ().** call, depe
eee0: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a nding on the obj
eef0: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 ect being opened
ef00: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
ef10: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
ef20: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c EN_MAIN_DB].** <
ef30: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
ef40: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a N_MAIN_JOURNAL].
ef50: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 ** <li> [SQLITE
ef60: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a _OPEN_TEMP_DB].*
ef70: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f * <li> [SQLITE_
ef80: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 OPEN_TEMP_JOURNA
ef90: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c L].** <li> [SQL
efa0: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 ITE_OPEN_TRANSIE
efb0: 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 NT_DB].** <li>
efc0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 [SQLITE_OPEN_SUB
efd0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e JOURNAL].** <li>
efe0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d [SQLITE_OPEN_M
eff0: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a ASTER_JOURNAL].*
f000: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f * <li> [SQLITE_
f010: 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 OPEN_WAL].** </u
f020: 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 l>)^.**.** The f
f030: 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e ile I/O implemen
f040: 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 tation can use t
f050: 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 he object type f
f060: 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 lags to.** chang
f070: 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61 e the way it dea
f080: 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 ls with files.
f090: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 For example, an
f0a0: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 application.** t
f0b0: 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 hat does not car
f0c0: 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 e about crash re
f0d0: 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 covery or rollba
f0e0: 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a ck might make.**
f0f0: 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a the open of a j
f100: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f ournal file a no
f110: 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 -op. Writes to
f120: 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 this journal wou
f130: 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f ld.** also be no
f140: 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 -ops, and any at
f150: 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 tempt to read th
f160: 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 e journal would
f170: 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 return.** SQLITE
f180: 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 _IOERR. Or the
f190: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d implementation m
f1a0: 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 ight recognize t
f1b0: 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a hat a database.*
f1c0: 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 * file will be d
f1d0: 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 oing page-aligne
f1e0: 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 d sector reads a
f1f0: 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 nd writes in a r
f200: 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 andom.** order a
f210: 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f nd set up its I/
f220: 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f O subsystem acco
f230: 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 rdingly..**.** S
f240: 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f QLite might also
f250: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 add one of the
f260: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 following flags
f270: 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 to the xOpen met
f280: 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a hod:.**.** <ul>.
f290: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
f2a0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f OPEN_DELETEONCLO
f2b0: 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c SE].** <li> [SQL
f2c0: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 ITE_OPEN_EXCLUSI
f2d0: 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a VE].** </ul>.**.
f2e0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f ** The [SQLITE_O
f2f0: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 PEN_DELETEONCLOS
f300: 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 E] flag means th
f310: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 e file should be
f320: 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e .** deleted when
f330: 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 it is closed.
f340: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 ^The [SQLITE_OPE
f350: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d N_DELETEONCLOSE]
f360: 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 .** will be set
f370: 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 for TEMP databas
f380: 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 es and their jou
f390: 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 rnals, transient
f3a0: 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 .** databases, a
f3b0: 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a nd subjournals..
f3c0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 **.** ^The [SQLI
f3d0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 TE_OPEN_EXCLUSIV
f3e0: 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 E] flag is alway
f3f0: 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e s used in conjun
f400: 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 ction.** with th
f410: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 e [SQLITE_OPEN_C
f420: 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 REATE] flag, whi
f430: 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 ch are both dire
f440: 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 ctly.** analogou
f450: 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 s to the O_EXCL
f460: 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 and O_CREAT flag
f470: 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f s of the POSIX o
f480: 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 pen().** API. T
f490: 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 he SQLITE_OPEN_E
f4a0: 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 XCLUSIVE flag, w
f4b0: 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 hen paired with
f4c0: 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f the .** SQLITE_O
f4d0: 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 PEN_CREATE, is u
f4e0: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 sed to indicate
f4f0: 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 that file should
f500: 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 always.** be cr
f510: 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 eated, and that
f520: 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 it is an error i
f530: 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 f it already exi
f540: 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 sts..** It is <i
f550: 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f >not</i> used to
f560: 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 indicate the fi
f570: 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 le should be ope
f580: 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c ned .** for excl
f590: 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a usive access..**
f5a0: 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a .** ^At least sz
f5b0: 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 OsFile bytes of
f5c0: 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 memory are alloc
f5d0: 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a ated by SQLite.*
f5e0: 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b * to hold the [
f5f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 sqlite3_file] st
f600: 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61 ructure passed a
f610: 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 s the third.** a
f620: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e rgument to xOpen
f630: 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 . The xOpen met
f640: 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 hod does not hav
f650: 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 e to.** allocate
f660: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 the structure;
f670: 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 it should just f
f680: 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 ill it in. Note
f690: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 that.** the xOp
f6a0: 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 en method must s
f6b0: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 et the sqlite3_f
f6c0: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 ile.pMethods to
f6d0: 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 either.** a vali
f6e0: 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 d [sqlite3_io_me
f6f0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 thods] object or
f700: 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e to NULL. xOpen
f710: 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 must do.** this
f720: 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 even if the ope
f730: 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 n fails. SQLite
f740: 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74 68 expects that th
f750: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 e sqlite3_file.p
f760: 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 Methods.** eleme
f770: 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 nt will be valid
f780: 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 after xOpen ret
f790: 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 urns regardless
f7a0: 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a of the success.*
f7b0: 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 * or failure of
f7c0: 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a the xOpen call..
f7d0: 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f **.** [[sqlite3_
f7e0: 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a vfs.xAccess]].**
f7f0: 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 ^The flags argu
f800: 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 ment to xAccess(
f810: 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 ) may be [SQLITE
f820: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a _ACCESS_EXISTS].
f830: 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 ** to test for t
f840: 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 he existence of
f850: 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 a file, or [SQLI
f860: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 TE_ACCESS_READWR
f870: 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 ITE] to.** test
f880: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 whether a file i
f890: 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 s readable and w
f8a0: 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c ritable, or [SQL
f8b0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d ITE_ACCESS_READ]
f8c0: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 .** to test whet
f8d0: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 her a file is at
f8e0: 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e least readable.
f8f0: 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 The file can
f900: 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 be a.** director
f910: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 y..**.** ^SQLite
f920: 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c will always all
f930: 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d ocate at least m
f940: 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 xPathname+1 byte
f950: 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 s for the.** out
f960: 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c put buffer xFull
f970: 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 Pathname. The e
f980: 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 xact size of the
f990: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a output buffer.*
f9a0: 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 * is also passed
f9b0: 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 as a parameter
f9c0: 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 to both methods
f9d0: 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 . If the output
f9e0: 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 buffer.** is not
f9f0: 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b large enough, [
fa00: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d SQLITE_CANTOPEN]
fa10: 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 should be retur
fa20: 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 ned. Since this
fa30: 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 is.** handled as
fa40: 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 a fatal error b
fa50: 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d y SQLite, vfs im
fa60: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 plementations sh
fa70: 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a ould endeavor.**
fa80: 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 to prevent this
fa90: 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 by setting mxPa
faa0: 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 thname to a suff
fab0: 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 iciently large v
fac0: 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 alue..**.** The
fad0: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 xRandomness(), x
fae0: 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e Sleep(), xCurren
faf0: 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 tTime(), and xCu
fb00: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 rrentTimeInt64()
fb10: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 .** interfaces a
fb20: 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 re not strictly
fb30: 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 a part of the fi
fb40: 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 lesystem, but th
fb50: 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 ey are.** includ
fb60: 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 ed in the VFS st
fb70: 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 ructure for comp
fb80: 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 leteness..** The
fb90: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 xRandomness() f
fba0: 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 unction attempts
fbb0: 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 to return nByte
fbc0: 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f s bytes.** of go
fbd0: 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f od-quality rando
fbe0: 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e mness into zOut.
fbf0: 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c The return val
fc00: 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 ue is.** the act
fc10: 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 ual number of by
fc20: 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 tes of randomnes
fc30: 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 s obtained..** T
fc40: 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 he xSleep() meth
fc50: 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61 od causes the ca
fc60: 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 lling thread to
fc70: 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 sleep for at.**
fc80: 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 least the number
fc90: 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 of microseconds
fca0: 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 given. ^The xC
fcb0: 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 urrentTime().**
fcc0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 method returns a
fcd0: 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 Julian Day Numb
fce0: 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 er for the curre
fcf0: 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 nt date and time
fd00: 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e as.** a floatin
fd10: 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a g point value..*
fd20: 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 * ^The xCurrentT
fd30: 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f imeInt64() metho
fd40: 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e d returns, as an
fd50: 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 integer, the Ju
fd60: 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 lian.** Day Numb
fd70: 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 er multiplied by
fd80: 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 86400000 (the n
fd90: 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 umber of millise
fda0: 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 conds in .** a 2
fdb0: 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 4-hour day). .*
fdc0: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 * ^SQLite will u
fdd0: 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 se the xCurrentT
fde0: 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f imeInt64() metho
fdf0: 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 d to get the cur
fe00: 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 rent.** date and
fe10: 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 time if that me
fe20: 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c thod is availabl
fe30: 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 e (if iVersion i
fe40: 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 s 2 or .** great
fe50: 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 er and the funct
fe60: 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e ion pointer is n
fe70: 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c ot NULL) and wil
fe80: 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 l fall back.** t
fe90: 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 o xCurrentTime()
fea0: 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 if xCurrentTime
feb0: 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 Int64() is unava
fec0: 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ilable..**.** ^T
fed0: 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c he xSetSystemCal
fee0: 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 l(), xGetSystemC
fef0: 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 all(), and xNest
ff00: 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 SystemCall() int
ff10: 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e erfaces.** are n
ff20: 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20 53 ot used by the S
ff30: 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 QLite core. The
ff40: 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 se optional inte
ff50: 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 rfaces are provi
ff60: 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 ded.** by some V
ff70: 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 FSes to facilita
ff80: 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 te testing of th
ff90: 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f e VFS code. By o
ffa0: 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 verriding .** sy
ffb0: 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 stem calls with
ffc0: 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 functions under
ffd0: 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 its control, a t
ffe0: 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a est program can.
fff0: 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c ** simulate faul
10000 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e ts and error con
10010 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 ditions that wou
10020 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 ld otherwise be
10030 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 difficult.** or
10040 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e impossible to in
10050 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f duce. The set o
10060 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 f system calls t
10070 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 hat can be overr
10080 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 idden.** varies
10090 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 from one VFS to
100a0 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f another, and fro
100b0 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 m one version of
100c0 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f the same VFS to
100d0 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 the.** next. A
100e0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 pplications that
100f0 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 use these inter
10100 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 faces must be pr
10110 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a epared for any.*
10120 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 * or all of thes
10130 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 e interfaces to
10140 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 be NULL or for t
10150 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f heir behavior to
10160 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 change.** from
10170 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 one release to t
10180 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 he next. Applic
10190 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 ations must not
101a0 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 attempt to acces
101b0 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 s.** any of thes
101c0 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 e methods if the
101d0 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 iVersion of the
101e0 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 VFS is less tha
101f0 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 n 3..*/.typedef
10200 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 struct sqlite3_v
10210 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a fs sqlite3_vfs;.
10220 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 typedef void (*s
10230 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 qlite3_syscall_p
10240 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 tr)(void);.struc
10250 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a t sqlite3_vfs {.
10260 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 int iVersion;
10270 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 /* St
10280 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 ructure version
10290 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c number (currentl
102a0 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a y 3) */. int sz
102b0 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 OsFile;
102c0 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 /* Size of su
102d0 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 bclassed sqlite3
102e0 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d _file */. int m
102f0 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 xPathname;
10300 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 /* Maximum f
10310 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e ile pathname len
10320 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 gth */. sqlite3
10330 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 _vfs *pNext;
10340 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 /* Next regist
10350 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f ered VFS */. co
10360 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b nst char *zName;
10370 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f /* Name o
10380 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 f this virtual f
10390 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 ile system */.
103a0 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 void *pAppData;
103b0 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e /* Poin
103c0 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 ter to applicati
103d0 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 on-specific data
103e0 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 */. int (*xOpe
103f0 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c n)(sqlite3_vfs*,
10400 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
10410 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 me, sqlite3_file
10420 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 *,.
10430 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 int flags, int
10440 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 *pOutFlags);.
10450 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 int (*xDelete)(s
10460 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e qlite3_vfs*, con
10470 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 st char *zName,
10480 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 int syncDir);.
10490 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 int (*xAccess)(s
104a0 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e qlite3_vfs*, con
104b0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 st char *zName,
104c0 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a int flags, int *
104d0 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 pResOut);. int
104e0 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 (*xFullPathname)
104f0 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 (sqlite3_vfs*, c
10500 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
10510 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 , int nOut, char
10520 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 *zOut);. void
10530 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 *(*xDlOpen)(sqli
10540 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 te3_vfs*, const
10550 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 char *zFilename)
10560 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 ;. void (*xDlEr
10570 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ror)(sqlite3_vfs
10580 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 *, int nByte, ch
10590 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 ar *zErrMsg);.
105a0 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 void (*(*xDlSym)
105b0 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f (sqlite3_vfs*,vo
105c0 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 id*, const char
105d0 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 *zSymbol))(void)
105e0 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c ;. void (*xDlCl
105f0 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ose)(sqlite3_vfs
10600 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 *, void*);. int
10610 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 (*xRandomness)(
10620 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e sqlite3_vfs*, in
10630 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a t nByte, char *z
10640 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 Out);. int (*xS
10650 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 leep)(sqlite3_vf
10660 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 s*, int microsec
10670 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 onds);. int (*x
10680 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c CurrentTime)(sql
10690 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c ite3_vfs*, doubl
106a0 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 e*);. int (*xGe
106b0 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 tLastError)(sqli
106c0 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 te3_vfs*, int, c
106d0 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a har *);. /*. *
106e0 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 * The methods ab
106f0 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 ove are in versi
10700 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 on 1 of the sqli
10710 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 te_vfs object.
10720 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 ** definition.
10730 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f Those that follo
10740 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 w are added in v
10750 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 ersion 2 or late
10760 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 r. */. int (*x
10770 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 CurrentTimeInt64
10780 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
10790 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b sqlite3_int64*);
107a0 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d . /*. ** The m
107b0 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 ethods above are
107c0 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 in versions 1 a
107d0 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 nd 2 of the sqli
107e0 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 te_vfs object..
107f0 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 ** Those below
10800 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 are for version
10810 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 3 and greater..
10820 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 */. int (*xSet
10830 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 SystemCall)(sqli
10840 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 te3_vfs*, const
10850 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c char *zName, sql
10860 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 ite3_syscall_ptr
10870 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 );. sqlite3_sys
10880 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 call_ptr (*xGetS
10890 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 ystemCall)(sqlit
108a0 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 e3_vfs*, const c
108b0 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 har *zName);. c
108c0 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 onst char *(*xNe
108d0 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 xtSystemCall)(sq
108e0 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 lite3_vfs*, cons
108f0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a t char *zName);.
10900 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 /*. ** The me
10910 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 thods above are
10920 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 in versions 1 th
10930 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 rough 3 of the s
10940 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 qlite_vfs object
10950 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 .. ** New field
10960 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 s may be appende
10970 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 d in figure vers
10980 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 ions. The iVers
10990 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 ion. ** value w
109a0 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 ill increment wh
109b0 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70 enever this happ
109c0 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f ens. . */.};../
109d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 *.** CAPI3REF: F
109e0 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 lags for the xAc
109f0 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a cess VFS method.
10a00 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 **.** These inte
10a10 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 ger constants ca
10a20 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65 n be used as the
10a30 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
10a40 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 to.** the xAcce
10a50 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 ss method of an
10a60 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 [sqlite3_vfs] ob
10a70 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 ject. They dete
10a80 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 rmine.** what ki
10a90 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e nd of permission
10aa0 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 s the xAccess me
10ab0 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 thod is looking
10ac0 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c for..** With SQL
10ad0 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 ITE_ACCESS_EXIST
10ae0 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d S, the xAccess m
10af0 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 ethod.** simply
10b00 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 checks whether t
10b10 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a he file exists..
10b20 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 ** With SQLITE_A
10b30 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c CCESS_READWRITE,
10b40 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 the xAccess met
10b50 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 hod.** checks wh
10b60 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 ether the named
10b70 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 directory is bot
10b80 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 h readable and w
10b90 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f ritable.** (in o
10ba0 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 ther words, if f
10bb0 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 iles can be adde
10bc0 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 d, removed, and
10bd0 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a renamed within.*
10be0 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 * the directory)
10bf0 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f ..** The SQLITE_
10c00 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 ACCESS_READWRITE
10c10 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 constant is cur
10c20 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 rently used only
10c30 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 by the.** [temp
10c40 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 _store_directory
10c50 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 pragma], though
10c60 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e this could chan
10c70 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a ge in a future.*
10c80 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c * release of SQL
10c90 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c ite..** With SQL
10ca0 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c ITE_ACCESS_READ,
10cb0 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 the xAccess met
10cc0 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 hod.** checks wh
10cd0 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 ether the file i
10ce0 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 s readable. The
10cf0 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 SQLITE_ACCESS_R
10d00 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a EAD constant is.
10d10 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 ** currently unu
10d20 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d sed, though it m
10d30 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 ight be used in
10d40 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 a future release
10d50 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a of.** SQLite..*
10d60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
10d70 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 _ACCESS_EXISTS
10d80 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 0.#define SQLI
10d90 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 TE_ACCESS_READWR
10da0 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 ITE 1 /* Used
10db0 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 by PRAGMA temp_s
10dc0 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a tore_directory *
10dd0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
10de0 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 _ACCESS_READ
10df0 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2 /* Unused
10e00 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 */../*.** CAPI3R
10e10 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 EF: Flags for th
10e20 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d e xShmLock VFS m
10e30 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ethod.**.** Thes
10e40 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 e integer consta
10e50 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 nts define the v
10e60 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f arious locking o
10e70 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c perations.** all
10e80 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68 6d owed by the xShm
10e90 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b Lock method of [
10ea0 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
10eb0 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c ds]. The.** fol
10ec0 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f lowing are the o
10ed0 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e nly legal combin
10ee0 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 ations of flags
10ef0 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f to the.** xShmLo
10f00 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a ck method:.**.**
10f10 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 <ul>.** <li> S
10f20 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c QLITE_SHM_LOCK |
10f30 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 SQLITE_SHM_SHAR
10f40 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 ED.** <li> SQLI
10f50 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 TE_SHM_LOCK | SQ
10f60 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 LITE_SHM_EXCLUSI
10f70 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 VE.** <li> SQLI
10f80 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 TE_SHM_UNLOCK |
10f90 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 SQLITE_SHM_SHARE
10fa0 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 D.** <li> SQLIT
10fb0 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 E_SHM_UNLOCK | S
10fc0 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 QLITE_SHM_EXCLUS
10fd0 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a IVE.** </ul>.**.
10fe0 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e ** When unlockin
10ff0 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 g, the same SHAR
11000 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 ED or EXCLUSIVE
11010 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 flag must be sup
11020 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 plied as.** was
11030 67 69 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 given on the cor
11040 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e responding lock.
11050 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 .**.** The xSh
11060 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e mLock method can
11070 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 transition betw
11080 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 een unlocked and
11090 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 SHARED or.** be
110a0 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 tween unlocked a
110b0 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 nd EXCLUSIVE. I
110c0 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 t cannot transit
110d0 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 ion between SHAR
110e0 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 ED.** and EXCLUS
110f0 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 IVE..*/.#define
11100 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 SQLITE_SHM_UNLOC
11110 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e K 1.#defin
11120 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 e SQLITE_SHM_LOC
11130 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 K 2.#def
11140 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 ine SQLITE_SHM_S
11150 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 HARED 4.#d
11160 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d efine SQLITE_SHM
11170 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a _EXCLUSIVE 8.
11180 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
11190 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 Maximum xShmLoc
111a0 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 k index.**.** Th
111b0 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f e xShmLock metho
111c0 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f d on [sqlite3_io
111d0 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 _methods] may us
111e0 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 e values.** betw
111f0 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 een 0 and this u
11200 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 pper bound as it
11210 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d s "offset" argum
11220 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 ent..** The SQLi
11230 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 te core will nev
11240 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 er attempt to ac
11250 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 quire or release
11260 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 a.** lock outsi
11270 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 de of this range
11280 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
11290 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 TE_SHM_NLOCK
112a0 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 8.../*.** CA
112b0 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 PI3REF: Initiali
112c0 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 ze The SQLite Li
112d0 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 brary.**.** ^The
112e0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
112f0 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e ize() routine in
11300 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a itializes the.**
11310 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e SQLite library.
11320 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 ^The sqlite3_s
11330 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e hutdown() routin
11340 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 e.** deallocates
11350 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 any resources t
11360 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 hat were allocat
11370 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e ed by sqlite3_in
11380 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 itialize()..** T
11390 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 hese routines ar
113a0 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 e designed to ai
113b0 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 d in process ini
113c0 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a tialization and.
113d0 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 ** shutdown on e
113e0 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e mbedded systems.
113f0 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 Workstation ap
11400 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 plications using
11410 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 .** SQLite norma
11420 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 lly do not need
11430 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 to invoke either
11440 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e of these routin
11450 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c es..**.** A call
11460 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 to sqlite3_init
11470 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 ialize() is an "
11480 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 effective" call
11490 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 if it is.** the
114a0 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 first time sqlit
114b0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
114c0 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e is invoked durin
114d0 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f g the lifetime o
114e0 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 f.** the process
114f0 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 , or if it is th
11500 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c e first time sql
11510 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
11520 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 ) is invoked.**
11530 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c following a call
11540 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 to sqlite3_shut
11550 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 down(). ^(Only
11560 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c an effective cal
11570 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f l.** of sqlite3_
11580 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 initialize() doe
11590 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 s any initializa
115a0 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 tion. All other
115b0 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 calls.** are ha
115c0 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e rmless no-ops.)^
115d0 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f .**.** A call to
115e0 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
115f0 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 n() is an "effec
11600 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 tive" call if it
11610 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a is the first.**
11620 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
11630 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 _shutdown() sinc
11640 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 e the last sqlit
11650 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e e3_initialize().
11660 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 ^(Only.** an e
11670 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f ffective call to
11680 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
11690 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 n() does any dei
116a0 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a nitialization..*
116b0 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 * All other vali
116c0 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 d calls to sqlit
116d0 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 e3_shutdown() ar
116e0 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 e harmless no-op
116f0 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 s.)^.**.** The s
11700 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
11710 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 e() interface is
11720 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 threadsafe, but
11730 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
11740 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 n().** is not.
11750 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 The sqlite3_shut
11760 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 down() interface
11770 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 must only be ca
11780 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 lled from a.** s
11790 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 ingle thread. A
117a0 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 ll open [databas
117b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d e connections] m
117c0 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e ust be closed an
117d0 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 d all.** other S
117e0 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 QLite resources
117f0 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 must be dealloca
11800 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 ted prior to inv
11810 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 oking.** sqlite3
11820 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a _shutdown()..**.
11830 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 ** Among other t
11840 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f hings, ^sqlite3_
11850 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c initialize() wil
11860 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 l invoke.** sqli
11870 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 te3_os_init().
11880 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 Similarly, ^sqli
11890 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a te3_shutdown().*
118a0 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 * will invoke sq
118b0 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a lite3_os_end()..
118c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
118d0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
118e0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
118f0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 [SQLITE_OK] on s
11900 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 uccess..** ^If f
11910 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 or some reason,
11920 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
11930 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 ze() is unable t
11940 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 o initialize.**
11950 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 the library (per
11960 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c haps it is unabl
11970 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 e to allocate a
11980 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 needed resource
11990 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 such.** as a mut
119a0 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 ex) it returns a
119b0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f n [error code] o
119c0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 ther than [SQLIT
119d0 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 E_OK]..**.** ^Th
119e0 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 e sqlite3_initia
119f0 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 lize() routine i
11a00 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 s called interna
11a10 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 lly by many othe
11a20 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 r.** SQLite inte
11a30 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 rfaces so that a
11a40 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 n application us
11a50 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e ually does not n
11a60 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 eed to.** invoke
11a70 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
11a80 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 ize() directly.
11a90 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 For example, [s
11aa0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a qlite3_open()].*
11ab0 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f * calls sqlite3_
11ac0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 initialize() so
11ad0 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 the SQLite libra
11ae0 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d ry will be autom
11af0 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 atically.** init
11b00 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 ialized when [sq
11b10 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 lite3_open()] is
11b20 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 called if it ha
11b30 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c s not be initial
11b40 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e ized.** already.
11b50 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 ^However, if S
11b60 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 QLite is compile
11b70 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 d with the [SQLI
11b80 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 TE_OMIT_AUTOINIT
11b90 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d ].** compile-tim
11ba0 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 e option, then t
11bb0 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c he automatic cal
11bc0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e ls to sqlite3_in
11bd0 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 itialize().** ar
11be0 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 e omitted and th
11bf0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 e application mu
11c00 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f st call sqlite3_
11c10 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 initialize() dir
11c20 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 ectly.** prior t
11c30 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 o using any othe
11c40 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 r SQLite interfa
11c50 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d ce. For maximum
11c60 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a portability,.**
11c70 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 it is recommend
11c80 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 ed that applicat
11c90 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f ions always invo
11ca0 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 ke sqlite3_initi
11cb0 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 alize().** direc
11cc0 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 tly prior to usi
11cd0 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c ng any other SQL
11ce0 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 ite interface.
11cf0 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a Future releases.
11d00 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 ** of SQLite may
11d10 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 require this.
11d20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 In other words,
11d30 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 the behavior exh
11d40 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 ibited.** when S
11d50 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 QLite is compile
11d60 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f d with [SQLITE_O
11d70 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 MIT_AUTOINIT] mi
11d80 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a ght become the.*
11d90 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 * default behavi
11da0 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 or in some futur
11db0 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c e release of SQL
11dc0 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ite..**.** The s
11dd0 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
11de0 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 routine does op
11df0 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 erating-system s
11e00 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 pecific.** initi
11e10 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 alization of the
11e20 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e SQLite library.
11e30 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 The sqlite3_os
11e40 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e _end().** routin
11e50 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 e undoes the eff
11e60 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f ect of sqlite3_o
11e70 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 s_init(). Typic
11e80 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 al tasks.** perf
11e90 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 ormed by these r
11ea0 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 outines include
11eb0 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 allocation or de
11ec0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 allocation.** of
11ed0 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 static resource
11ee0 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f s, initializatio
11ef0 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 n of global vari
11f00 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e ables,.** settin
11f10 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b g up a default [
11f20 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 sqlite3_vfs] mod
11f30 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 ule, or setting
11f40 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 up.** a default
11f50 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 configuration us
11f60 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e ing [sqlite3_con
11f70 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 fig()]..**.** Th
11f80 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 e application sh
11f90 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b ould never invok
11fa0 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 e either sqlite3
11fb0 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 _os_init().** or
11fc0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 sqlite3_os_end(
11fd0 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 ) directly. The
11fe0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f application sho
11ff0 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a uld only invoke.
12000 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 ** sqlite3_initi
12010 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 alize() and sqli
12020 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 te3_shutdown().
12030 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f The sqlite3_os_
12040 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 init().** interf
12050 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 ace is called au
12060 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 tomatically by s
12070 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
12080 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 e() and.** sqlit
12090 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 e3_os_end() is c
120a0 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 alled by sqlite3
120b0 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 _shutdown(). Ap
120c0 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 propriate.** imp
120d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 lementations for
120e0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
120f0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f () and sqlite3_o
12100 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 s_end().** are b
12110 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 uilt into SQLite
12120 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 when it is comp
12130 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 iled for Unix, W
12140 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e indows, or OS/2.
12150 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d .** When [custom
12160 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 builds | built
12170 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f for other platfo
12180 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 rms].** (using t
12190 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 he [SQLITE_OS_OT
121a0 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 HER=1] compile-t
121b0 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 ime.** option) t
121c0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d he application m
121d0 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 ust supply a sui
121e0 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 table implementa
121f0 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 tion for.** sqli
12200 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e te3_os_init() an
12210 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 d sqlite3_os_end
12220 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 (). An applicat
12230 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 ion-supplied.**
12240 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
12250 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 f sqlite3_os_ini
12260 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f t() or sqlite3_o
12270 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 s_end().** must
12280 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f return [SQLITE_O
12290 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e K] on success an
122a0 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 d some other [er
122b0 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a ror code] upon.*
122c0 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51 * failure..*/.SQ
122d0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
122e0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
122f0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 te3_initialize(v
12300 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 oid);.SQLITE_API
12310 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
12320 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 68 75 74 ALL sqlite3_shut
12330 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 down(void);.SQLI
12340 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
12350 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
12360 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 3_os_init(void);
12370 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
12380 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
12390 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f qlite3_os_end(vo
123a0 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 id);../*.** CAPI
123b0 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 3REF: Configurin
123c0 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 g The SQLite Lib
123d0 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 rary.**.** The s
123e0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
123f0 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 interface is use
12400 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c d to make global
12410 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a configuration.*
12420 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c * changes to SQL
12430 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 ite in order to
12440 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 tune SQLite to t
12450 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 he specific need
12460 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c s of.** the appl
12470 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 ication. The de
12480 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 fault configurat
12490 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 ion is recommend
124a0 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 ed for most.** a
124b0 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 pplications and
124c0 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 so this routine
124d0 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e is usually not n
124e0 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 ecessary. It is
124f0 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 .** provided to
12500 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 support rare app
12510 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 lications with u
12520 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a nusual needs..**
12530 0a 2a 2a 20 3c 62 3e 54 68 65 20 73 71 6c 69 74 .** <b>The sqlit
12540 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 e3_config() inte
12550 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 rface is not thr
12560 65 61 64 73 61 66 65 2e 20 54 68 65 20 61 70 70 eadsafe. The app
12570 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 lication.** must
12580 20 65 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 ensure that no
12590 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 other SQLite int
125a0 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f erfaces are invo
125b0 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 ked by other.**
125c0 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 threads while sq
125d0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 lite3_config() i
125e0 73 20 72 75 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a s running.</b>.*
125f0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
12600 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 _config() interf
12610 61 63 65 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 ace.** may only
12620 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 be invoked prior
12630 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 to library init
12640 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 ialization using
12650 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 .** [sqlite3_ini
12660 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 tialize()] or af
12670 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 ter shutdown by
12680 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 [sqlite3_shutdow
12690 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c n()]..** ^If sql
126a0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 ite3_config() is
126b0 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 called after [s
126c0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
126d0 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a e()] and before.
126e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 ** [sqlite3_shut
126f0 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 down()] then it
12700 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 will return SQLI
12710 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f TE_MISUSE..** No
12720 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 te, however, tha
12730 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 t ^sqlite3_confi
12740 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 g() can be calle
12750 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 d as part of the
12760 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
12770 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 on of an applica
12780 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 tion-defined [sq
12790 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d lite3_os_init()]
127a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 ..**.** The firs
127b0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 t argument to sq
127c0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 lite3_config() i
127d0 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 s an integer.**
127e0 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f [configuration o
127f0 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 ption] that dete
12800 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 rmines.** what p
12810 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 roperty of SQLit
12820 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 e is to be confi
12830 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 gured. Subseque
12840 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 nt arguments.**
12850 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f vary depending o
12860 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 n the [configura
12870 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 tion option].**
12880 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 in the first arg
12890 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 ument..**.** ^Wh
128a0 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 en a configurati
128b0 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 on option is set
128c0 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 , sqlite3_config
128d0 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 () returns [SQLI
128e0 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 TE_OK]..** ^If t
128f0 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b he option is unk
12900 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 nown or SQLite i
12910 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 s unable to set
12920 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 the option.** th
12930 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 en this routine
12940 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 returns a non-ze
12950 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e ro [error code].
12960 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
12970 6e 74 20 53 51 4c 49 54 45 5f 43 44 45 43 4c 20 nt SQLITE_CDECL
12980 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 sqlite3_config(i
12990 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a nt, ...);../*.**
129a0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 CAPI3REF: Confi
129b0 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f gure database co
129c0 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 nnections.** MET
129d0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a HOD: sqlite3.**.
129e0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 ** The sqlite3_d
129f0 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 b_config() inter
12a00 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 face is used to
12a10 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 make configurati
12a20 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f on.** changes to
12a30 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e a [database con
12a40 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 nection]. The i
12a50 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 nterface is simi
12a60 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 lar to.** [sqlit
12a70 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 e3_config()] exc
12a80 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61 ept that the cha
12a90 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 nges apply to a
12aa0 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 single.** [datab
12ab0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
12ac0 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 (specified in th
12ad0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
12ae0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 )..**.** The sec
12af0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ond argument to
12b00 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 sqlite3_db_confi
12b10 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 g(D,V,...) is t
12b20 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 he.** [SQLITE_DB
12b30 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 CONFIG_LOOKASIDE
12b40 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e | configuration
12b50 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 verb] - an inte
12b60 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 ger code .** tha
12b70 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 t indicates what
12b80 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b aspect of the [
12b90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
12ba0 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f ion] is being co
12bb0 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 nfigured..** Sub
12bc0 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 sequent argument
12bd0 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 s vary depending
12be0 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 on the configur
12bf0 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a ation verb..**.*
12c00 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 * ^Calls to sqli
12c10 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 te3_db_config()
12c20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b return SQLITE_OK
12c30 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a if and only if.
12c40 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 ** the call is c
12c50 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73 onsidered succes
12c60 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f sful..*/.SQLITE_
12c70 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 43 API int SQLITE_C
12c80 44 45 43 4c 20 73 71 6c 69 74 65 33 5f 64 62 5f DECL sqlite3_db_
12c90 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c config(sqlite3*,
12ca0 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a int op, ...);..
12cb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
12cc0 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f Memory Allocatio
12cd0 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a n Routines.**.**
12ce0 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 An instance of
12cf0 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 this object defi
12d00 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 nes the interfac
12d10 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 e between SQLite
12d20 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 .** and low-leve
12d30 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 l memory allocat
12d40 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a ion routines..**
12d50 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 .** This object
12d60 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 is used in only
12d70 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 one place in the
12d80 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
12d90 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 e..** A pointer
12da0 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f to an instance o
12db0 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 f this object is
12dc0 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f the argument to
12dd0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e .** [sqlite3_con
12de0 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 fig()] when the
12df0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
12e00 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 tion is.** [SQLI
12e10 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 TE_CONFIG_MALLOC
12e20 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e ] or [SQLITE_CON
12e30 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 FIG_GETMALLOC].
12e40 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 .** By creating
12e50 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 an instance of
12e60 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 this object.** a
12e70 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f nd passing it to
12e80 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
12e90 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ]([SQLITE_CONFIG
12ea0 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 _MALLOC]).** dur
12eb0 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ing configuratio
12ec0 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f n, an applicatio
12ed0 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e n can specify an
12ee0 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 alternative.**
12ef0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
12f00 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 n subsystem for
12f10 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f SQLite to use fo
12f20 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 r all of its.**
12f30 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e dynamic memory n
12f40 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 eeds..**.** Note
12f50 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d that SQLite com
12f60 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 es with several
12f70 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 [built-in memory
12f80 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 allocators].**
12f90 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74 that are perfect
12fa0 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 ly adequate for
12fb0 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 the overwhelming
12fc0 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 majority of app
12fd0 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 lications.** and
12fe0 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 that this objec
12ff0 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c t is only useful
13000 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 to a tiny minor
13010 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 ity of applicati
13020 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 ons.** with spec
13030 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 ialized memory a
13040 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 llocation requir
13050 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 ements. This ob
13060 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 ject is.** also
13070 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 used during test
13080 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e ing of SQLite in
13090 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 order to specif
130a0 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 y an alternative
130b0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 .** memory alloc
130c0 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 ator that simula
130d0 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f tes memory out-o
130e0 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 f-memory conditi
130f0 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 ons in.** order
13100 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53 to verify that S
13110 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 QLite recovers g
13120 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 racefully from s
13130 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e uch.** condition
13140 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 s..**.** The xMa
13150 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 lloc, xRealloc,
13160 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 and xFree method
13170 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 s must work like
13180 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 the.** malloc()
13190 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 , realloc() and
131a0 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 free() functions
131b0 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 from the standa
131c0 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a rd C library..**
131d0 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 ^SQLite guarant
131e0 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63 ees that the sec
131f0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a ond argument to.
13200 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 ** xRealloc is a
13210 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 lways a value re
13220 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f turned by a prio
13230 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 r call to xRound
13240 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 up..**.** xSize
13250 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 should return th
13260 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 e allocated size
13270 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c of a memory all
13280 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 ocation.** previ
13290 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 ously obtained f
132a0 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 rom xMalloc or x
132b0 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c Realloc. The al
132c0 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 located size.**
132d0 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 is always at lea
132e0 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65 st as big as the
132f0 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 requested size
13300 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 but may be large
13310 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f r..**.** The xRo
13320 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 undup method ret
13330 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 urns what would
13340 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 be the allocated
13350 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 size of.** a me
13360 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
13370 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c given a particul
13380 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a ar requested siz
13390 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a e. Most memory.
133a0 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f ** allocators ro
133b0 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c und up memory al
133c0 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 locations at lea
133d0 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d st to the next m
133e0 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e ultiple.** of 8.
133f0 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 Some allocator
13400 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 s round up to a
13410 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 larger multiple
13420 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 or to a power of
13430 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 2..** Every mem
13440 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 ory allocation r
13450 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e equest coming in
13460 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 through [sqlite
13470 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 3_malloc()].** o
13480 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c r [sqlite3_reall
13490 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c oc()] first call
134a0 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 s xRoundup. If
134b0 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 xRoundup returns
134c0 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 0, .** that cau
134d0 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f ses the correspo
134e0 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c nding memory all
134f0 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e ocation to fail.
13500 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 .**.** The xInit
13510 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 method initiali
13520 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 zes the memory a
13530 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 llocator. For e
13540 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 xample,.** it mi
13550 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 ght allocate any
13560 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 require mutexes
13570 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 or initialize i
13580 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 nternal data.**
13590 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 structures. The
135a0 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f xShutdown metho
135b0 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e d is invoked (in
135c0 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 directly) by.**
135d0 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 [sqlite3_shutdow
135e0 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 n()] and should
135f0 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 deallocate any r
13600 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 esources acquire
13610 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 d.** by xInit.
13620 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 The pAppData poi
13630 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20 nter is used as
13640 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 the only paramet
13650 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 er to.** xInit a
13660 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a nd xShutdown..**
13670 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 .** SQLite holds
13680 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 the [SQLITE_MUT
13690 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 EX_STATIC_MASTER
136a0 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 ] mutex when it
136b0 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 invokes.** the x
136c0 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 Init method, so
136d0 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 the xInit method
136e0 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 need not be thr
136f0 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a eadsafe. The.**
13700 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f xShutdown metho
13710 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 d is only called
13720 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 from [sqlite3_s
13730 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 hutdown()] so it
13740 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 does.** not nee
13750 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 d to be threadsa
13760 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 fe either. For
13770 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 all other method
13780 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c s, SQLite.** hol
13790 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d ds the [SQLITE_M
137a0 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d UTEX_STATIC_MEM]
137b0 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 mutex as long a
137c0 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 s the.** [SQLITE
137d0 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 _CONFIG_MEMSTATU
137e0 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e S] configuration
137f0 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 option is turne
13800 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 d on (which.** i
13810 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 t is by default)
13820 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 and so the meth
13830 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 ods are automati
13840 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 cally serialized
13850 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 ..** However, if
13860 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
13870 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 MEMSTATUS] is di
13880 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 sabled, then the
13890 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 other.** method
138a0 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 s must be thread
138b0 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b safe or else mak
138c0 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 e their own arra
138d0 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 ngements for.**
138e0 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a serialization..*
138f0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c *.** SQLite will
13900 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 never invoke xI
13910 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 nit() more than
13920 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 once without an
13930 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 intervening.** c
13940 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e all to xShutdown
13950 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 ()..*/.typedef s
13960 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 truct sqlite3_me
13970 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 m_methods sqlite
13980 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 3_mem_methods;.s
13990 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 truct sqlite3_me
139a0 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f m_methods {. vo
139b0 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 id *(*xMalloc)(i
139c0 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 nt); /*
139d0 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f Memory allocatio
139e0 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 n function */.
139f0 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f void (*xFree)(vo
13a00 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f id*); /
13a10 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 * Free a prior a
13a20 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 llocation */. v
13a30 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 oid *(*xRealloc)
13a40 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a (void*,int); /*
13a50 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 Resize an alloc
13a60 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 ation */. int (
13a70 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 *xSize)(void*);
13a80 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 /* Ret
13a90 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 urn the size of
13aa0 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f an allocation */
13ab0 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 . int (*xRoundu
13ac0 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 p)(int);
13ad0 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 /* Round up re
13ae0 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c quest size to al
13af0 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f location size */
13b00 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 . int (*xInit)(
13b10 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 void*);
13b20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 /* Initialize
13b30 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 the memory alloc
13b40 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 ator */. void (
13b50 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 *xShutdown)(void
13b60 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e *); /* Dein
13b70 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d itialize the mem
13b80 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f ory allocator */
13b90 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 . void *pAppDat
13ba0 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 a;
13bb0 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f /* Argument to
13bc0 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 xInit() and xSh
13bd0 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a utdown() */.};..
13be0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
13bf0 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 Configuration Op
13c00 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 tions.** KEYWORD
13c10 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f S: {configuratio
13c20 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 n option}.**.**
13c30 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 These constants
13c40 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c are the availabl
13c50 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 e integer config
13c60 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 uration options
13c70 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 that.** can be p
13c80 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 assed as the fir
13c90 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 st argument to t
13ca0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 he [sqlite3_conf
13cb0 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e ig()] interface.
13cc0 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 .**.** New confi
13cd0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 guration options
13ce0 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e may be added in
13cf0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 future releases
13d00 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 of SQLite..** E
13d10 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 xisting configur
13d20 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 ation options mi
13d30 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e ght be discontin
13d40 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f ued. Applicatio
13d50 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 ns.** should che
13d60 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f ck the return co
13d70 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 de from [sqlite3
13d80 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 _config()] to ma
13d90 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 ke sure that.**
13da0 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e the call worked.
13db0 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 The [sqlite3_c
13dc0 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 onfig()] interfa
13dd0 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 ce will return a
13de0 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 .** non-zero [er
13df0 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 ror code] if a d
13e00 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 iscontinued or u
13e10 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 nsupported confi
13e20 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a guration option.
13e30 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a ** is invoked..*
13e40 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 *.** <dl>.** [[S
13e50 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e QLITE_CONFIG_SIN
13e60 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e GLETHREAD]] <dt>
13e70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 SQLITE_CONFIG_SI
13e80 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a NGLETHREAD</dt>.
13e90 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 ** <dd>There are
13ea0 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f no arguments to
13eb0 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e this option. ^
13ec0 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 This option sets
13ed0 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 the.** [threadi
13ee0 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 ng mode] to Sing
13ef0 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f le-thread. In o
13f00 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 ther words, it d
13f10 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d isables.** all m
13f20 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 utexing and puts
13f30 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d SQLite into a m
13f40 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e ode where it can
13f50 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a only be used.**
13f60 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 by a single thr
13f70 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 ead. ^If SQLit
13f80 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 e is compiled wi
13f90 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 th.** the [SQLIT
13fa0 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 E_THREADSAFE | S
13fb0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
13fc0 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 =0] compile-time
13fd0 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 option then.**
13fe0 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 it is not possib
13ff0 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 le to change the
14000 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
14010 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 ] from its defau
14020 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 lt.** value of S
14030 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 ingle-thread and
14040 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e so [sqlite3_con
14050 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 fig()] will retu
14060 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 rn .** [SQLITE_E
14070 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 RROR] if called
14080 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f with the SQLITE_
14090 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 CONFIG_SINGLETHR
140a0 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 EAD.** configura
140b0 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 tion option.</dd
140c0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
140d0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 _CONFIG_MULTITHR
140e0 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 EAD]] <dt>SQLITE
140f0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 _CONFIG_MULTITHR
14100 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e EAD</dt>.** <dd>
14110 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 There are no arg
14120 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f uments to this o
14130 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 ption. ^This op
14140 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a tion sets the.**
14150 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
14160 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 ] to Multi-threa
14170 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 d. In other wor
14180 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a ds, it disables.
14190 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b ** mutexing on [
141a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
141b0 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 ion] and [prepar
141c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 ed statement] ob
141d0 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 jects..** The ap
141e0 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 plication is res
141f0 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 ponsible for ser
14200 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 ializing access
14210 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 to.** [database
14220 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 connections] and
14230 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
14240 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 ments]. But oth
14250 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 er mutexes.** ar
14260 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 e enabled so tha
14270 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 t SQLite will be
14280 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 safe to use in
14290 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 a multi-threaded
142a0 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 .** environment
142b0 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 as long as no tw
142c0 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 o threads attemp
142d0 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d t to use the sam
142e0 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 e.** [database c
142f0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 onnection] at th
14300 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 e same time. ^I
14310 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 f SQLite is comp
14320 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 iled with.** the
14330 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 [SQLITE_THREADS
14340 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 AFE | SQLITE_THR
14350 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 EADSAFE=0] compi
14360 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 le-time option t
14370 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 hen.** it is not
14380 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 possible to set
14390 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 the Multi-threa
143a0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 d [threading mod
143b0 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 e] and.** [sqlit
143c0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c e3_config()] wil
143d0 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 l return [SQLITE
143e0 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 _ERROR] if calle
143f0 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 d with the.** SQ
14400 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 LITE_CONFIG_MULT
14410 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 ITHREAD configur
14420 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 ation option.</d
14430 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
14440 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 E_CONFIG_SERIALI
14450 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 ZED]] <dt>SQLITE
14460 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a _CONFIG_SERIALIZ
14470 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 ED</dt>.** <dd>T
14480 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 here are no argu
14490 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 ments to this op
144a0 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 tion. ^This opt
144b0 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 ion sets the.**
144c0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d [threading mode]
144d0 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 to Serialized.
144e0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 In other words,
144f0 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 this option enab
14500 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 les.** all mutex
14510 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 es including the
14520 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 recursive.** mu
14530 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 texes on [databa
14540 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 se connection] a
14550 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 nd [prepared sta
14560 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e tement] objects.
14570 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 .** In this mode
14580 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64 (which is the d
14590 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 efault when SQLi
145a0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
145b0 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 ith.** [SQLITE_T
145c0 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 HREADSAFE=1]) th
145d0 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 e SQLite library
145e0 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 will itself ser
145f0 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a ialize access.**
14600 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f to [database co
14610 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b nnections] and [
14620 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
14630 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 nts] so that the
14640 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 .** application
14650 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 is free to use t
14660 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 he same [databas
14670 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 e connection] or
14680 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 the.** same [pr
14690 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
146a0 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 ] in different t
146b0 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 hreads at the sa
146c0 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 me time..** ^If
146d0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
146e0 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b ed with.** the [
146f0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
14700 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 E | SQLITE_THREA
14710 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 DSAFE=0] compile
14720 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 -time option the
14730 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 n.** it is not p
14740 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 ossible to set t
14750 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 he Serialized [t
14760 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 hreading mode] a
14770 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 nd.** [sqlite3_c
14780 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 onfig()] will re
14790 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 turn [SQLITE_ERR
147a0 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 OR] if called wi
147b0 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 th the.** SQLITE
147c0 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a _CONFIG_SERIALIZ
147d0 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ED configuration
147e0 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a option.</dd>.**
147f0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
14800 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 FIG_MALLOC]] <dt
14810 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d >SQLITE_CONFIG_M
14820 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ALLOC</dt>.** <d
14830 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f d> ^(The SQLITE_
14840 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 CONFIG_MALLOC op
14850 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e tion takes a sin
14860 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 gle argument whi
14870 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e ch is .** a poin
14880 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e ter to an instan
14890 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 ce of the [sqlit
148a0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 e3_mem_methods]
148b0 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 structure..** Th
148c0 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 e argument speci
148d0 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 fies.** alternat
148e0 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 ive low-level me
148f0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
14900 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 routines to be u
14910 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a sed in place of.
14920 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c ** the memory al
14930 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 location routine
14940 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c s built into SQL
14950 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d ite.)^ ^SQLite m
14960 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 akes.** its own
14970 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 private copy of
14980 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 the content of t
14990 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f he [sqlite3_mem_
149a0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 methods] structu
149b0 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 re.** before the
149c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
149d0 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 ()] call returns
149e0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 .</dd>.**.** [[S
149f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
14a00 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c MALLOC]] <dt>SQL
14a10 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 ITE_CONFIG_GETMA
14a20 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 LLOC</dt>.** <dd
14a30 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 > ^(The SQLITE_C
14a40 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 ONFIG_GETMALLOC
14a50 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 option takes a s
14a60 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 ingle argument w
14a70 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 hich.** is a poi
14a80 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 nter to an insta
14a90 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 nce of the [sqli
14aa0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d te3_mem_methods]
14ab0 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 structure..** T
14ac0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f he [sqlite3_mem_
14ad0 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 methods].** stru
14ae0 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 cture is filled
14af0 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 with the current
14b00 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 ly defined memor
14b10 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 y allocation rou
14b20 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 tines.)^.** This
14b30 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 option can be u
14b40 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 sed to overload
14b50 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f the default memo
14b60 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a ry allocation.**
14b70 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 routines with a
14b80 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69 wrapper that si
14b90 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 mulations memory
14ba0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c allocation fail
14bb0 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 ure or.** tracks
14bc0 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 memory usage, f
14bd0 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 or example. </dd
14be0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
14bf0 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 _CONFIG_MEMSTATU
14c00 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 S]] <dt>SQLITE_C
14c10 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c ONFIG_MEMSTATUS<
14c20 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 /dt>.** <dd> ^Th
14c30 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
14c40 4d 45 4d 53 54 41 54 55 53 20 6f 70 74 69 6f 6e MEMSTATUS option
14c50 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 takes single ar
14c60 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 gument of type i
14c70 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 nt,.** interpret
14c80 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c ed as a boolean,
14c90 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f which enables o
14ca0 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 r disables the c
14cb0 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 ollection of.**
14cc0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
14cd0 6e 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 n statistics. ^(
14ce0 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f When memory allo
14cf0 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 cation statistic
14d00 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 s are.** disable
14d10 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 d, the following
14d20 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
14d30 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 es become non-op
14d40 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 erational:.**
14d50 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b <ul>.** <li> [
14d60 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 sqlite3_memory_u
14d70 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e sed()].** <li>
14d80 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 [sqlite3_memory
14d90 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a _highwater()].**
14da0 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 <li> [sqlite3
14db0 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 _soft_heap_limit
14dc0 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 64()].** <li>
14dd0 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 36 [sqlite3_status6
14de0 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 4()].** </ul>)
14df0 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c ^.** ^Memory all
14e00 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 ocation statisti
14e10 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 cs are enabled b
14e20 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 y default unless
14e30 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f SQLite is.** co
14e40 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c mpiled with [SQL
14e50 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 ITE_DEFAULT_MEMS
14e60 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 TATUS]=0 in whic
14e70 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a h case memory.**
14e80 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 allocation stat
14e90 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62 istics are disab
14ea0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a led by default..
14eb0 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b ** </dd>.**.** [
14ec0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 [SQLITE_CONFIG_S
14ed0 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c CRATCH]] <dt>SQL
14ee0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 ITE_CONFIG_SCRAT
14ef0 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 CH</dt>.** <dd>
14f00 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 ^The SQLITE_CONF
14f10 49 47 5f 53 43 52 41 54 43 48 20 6f 70 74 69 6f IG_SCRATCH optio
14f20 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 n specifies a st
14f30 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 atic memory buff
14f40 65 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 er.** that SQLit
14f50 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20 73 63 e can use for sc
14f60 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 5e ratch memory. ^
14f70 28 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 (There are three
14f80 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f arguments.** to
14f90 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 SQLITE_CONFIG_S
14fa0 43 52 41 54 43 48 3a 20 20 41 20 70 6f 69 6e 74 CRATCH: A point
14fb0 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 er an 8-byte.**
14fc0 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 aligned memory b
14fd0 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 uffer from which
14fe0 20 74 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c the scratch all
14ff0 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 ocations will be
15000 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 .** drawn, the s
15010 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 ize of each scra
15020 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 tch allocation (
15030 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 sz),.** and the
15040 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
15050 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 f scratch alloca
15060 74 69 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20 tions (N).)^.**
15070 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
15080 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 nt must be a poi
15090 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 nter to an 8-byt
150a0 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 e aligned buffer
150b0 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 .** of at least
150c0 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 sz*N bytes of me
150d0 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 mory..** ^SQLite
150e0 20 77 69 6c 6c 20 6e 6f 74 20 75 73 65 20 6d 6f will not use mo
150f0 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 re than one scra
15100 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72 20 tch buffers per
15110 74 68 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69 thread..** ^SQLi
15120 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 te will never re
15130 71 75 65 73 74 20 61 20 73 63 72 61 74 63 68 20 quest a scratch
15140 62 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d buffer that is m
15150 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 ore than 6.** ti
15160 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 mes the database
15170 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e page size..** ^
15180 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 If SQLite needs
15190 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c needs additional
151a0 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f .** scratch memo
151b0 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 ry beyond what i
151c0 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 s provided by th
151d0 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e is configuration
151e0 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a option, then .*
151f0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f * [sqlite3_mallo
15200 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 c()] will be use
15210 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 d to obtain the
15220 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 70 memory needed.<p
15230 3e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 61 >.** ^When the a
15240 70 70 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76 69 pplication provi
15250 64 65 73 20 61 6e 79 20 61 6d 6f 75 6e 74 20 6f des any amount o
15260 66 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 f scratch memory
15270 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 using.** SQLITE
15280 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 2c _CONFIG_SCRATCH,
15290 20 53 51 4c 69 74 65 20 61 76 6f 69 64 73 20 75 SQLite avoids u
152a0 6e 6e 65 63 65 73 73 61 72 79 20 6c 61 72 67 65 nnecessary large
152b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c .** [sqlite3_mal
152c0 6c 6f 63 7c 68 65 61 70 20 61 6c 6c 6f 63 61 74 loc|heap allocat
152d0 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 20 63 ions]..** This c
152e0 61 6e 20 68 65 6c 70 20 5b 52 6f 62 73 6f 6e 20 an help [Robson
152f0 70 72 6f 6f 66 7c 70 72 65 76 65 6e 74 20 6d 65 proof|prevent me
15300 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
15310 66 61 69 6c 75 72 65 73 5d 20 64 75 65 20 74 6f failures] due to
15320 20 68 65 61 70 0a 2a 2a 20 66 72 61 67 6d 65 6e heap.** fragmen
15330 74 61 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65 tation in low-me
15340 6d 6f 72 79 20 65 6d 62 65 64 64 65 64 20 73 79 mory embedded sy
15350 73 74 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a stems..** </dd>.
15360 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
15370 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d ONFIG_PAGECACHE]
15380 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
15390 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 FIG_PAGECACHE</d
153a0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 t>.** <dd> ^The
153b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 SQLITE_CONFIG_PA
153c0 47 45 43 41 43 48 45 20 6f 70 74 69 6f 6e 20 73 GECACHE option s
153d0 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 pecifies a stati
153e0 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 0a c memory buffer.
153f0 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 ** that SQLite c
15400 61 6e 20 75 73 65 20 66 6f 72 20 74 68 65 20 64 an use for the d
15410 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63 atabase page cac
15420 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61 he with the defa
15430 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 ult page.** cach
15440 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
15450 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 . .** This conf
15460 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 iguration should
15470 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 not be used if
15480 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 an application-d
15490 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 efine page.** ca
154a0 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 che implementati
154b0 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 on is loaded usi
154c0 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 ng the [SQLITE_C
154d0 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 0a 2a ONFIG_PCACHE2].*
154e0 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 * configuration
154f0 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 54 68 65 72 option..** ^Ther
15500 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 e are three argu
15510 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f ments to SQLITE_
15520 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 CONFIG_PAGECACHE
15530 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a : A pointer to.*
15540 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 * 8-byte aligned
15550 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 .** memory, the
15560 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 size of each pag
15570 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 e buffer (sz), a
15580 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 nd the number of
15590 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 pages (N)..** T
155a0 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 he sz argument s
155b0 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a hould be the siz
155c0 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 e of the largest
155d0 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a database page.*
155e0 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 * (a power of tw
155f0 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e o between 512 an
15600 64 20 36 35 35 33 36 29 20 70 6c 75 73 20 73 6f d 65536) plus so
15610 6d 65 20 65 78 74 72 61 20 62 79 74 65 73 20 66 me extra bytes f
15620 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 or each.** page
15630 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 6e 75 header. ^The nu
15640 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20 62 79 mber of extra by
15650 74 65 73 20 6e 65 65 64 65 64 20 62 79 20 74 68 tes needed by th
15660 65 20 70 61 67 65 20 68 65 61 64 65 72 0a 2a 2a e page header.**
15670 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e can be determin
15680 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 ed using the [SQ
15690 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 LITE_CONFIG_PCAC
156a0 48 45 5f 48 44 52 53 5a 5d 20 6f 70 74 69 6f 6e HE_HDRSZ] option
156b0 20 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 .** to [sqlite3
156c0 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 20 5e _config()]..** ^
156d0 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 It is harmless,
156e0 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 apart from the w
156f0 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a asted memory,.**
15700 20 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61 for the sz para
15710 6d 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67 meter to be larg
15720 65 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72 er than necessar
15730 79 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a y. The first.**
15740 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 argument should
15750 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 pointer to an 8
15760 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 6c -byte aligned bl
15770 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 74 68 ock of memory th
15780 61 74 0a 2a 2a 20 69 73 20 61 74 20 6c 65 61 73 at.** is at leas
15790 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 t sz*N bytes of
157a0 6d 65 6d 6f 72 79 2c 20 6f 74 68 65 72 77 69 73 memory, otherwis
157b0 65 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 e subsequent beh
157c0 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 avior is.** unde
157d0 66 69 6e 65 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 fined..** ^SQLit
157e0 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d e will use the m
157f0 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 emory provided b
15800 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 y the first argu
15810 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 ment to satisfy
15820 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 its.** memory ne
15830 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 eds for the firs
15840 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 t N pages that i
15850 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e t adds to cache.
15860 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c ^If additional
15870 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d .** page cache m
15880 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 emory is needed
15890 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 beyond what is p
158a0 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 rovided by this
158b0 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 option, then.**
158c0 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b SQLite goes to [
158d0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
158e0 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 ] for the additi
158f0 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 onal storage spa
15900 63 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b ce.</dd>.**.** [
15910 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 [SQLITE_CONFIG_H
15920 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 EAP]] <dt>SQLITE
15930 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 _CONFIG_HEAP</dt
15940 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 >.** <dd> ^The S
15950 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 QLITE_CONFIG_HEA
15960 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 P option specifi
15970 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f es a static memo
15980 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20 74 68 ry buffer .** th
15990 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 at SQLite will u
159a0 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 se for all of it
159b0 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 s dynamic memory
159c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 allocation need
159d0 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f 73 s.** beyond thos
159e0 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 62 e provided for b
159f0 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 y [SQLITE_CONFIG
15a00 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 0a 2a 2a _SCRATCH] and.**
15a10 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
15a20 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e PAGECACHE]..** ^
15a30 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 The SQLITE_CONFI
15a40 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 69 73 G_HEAP option is
15a50 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 only available
15a60 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d if SQLite is com
15a70 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65 69 piled.** with ei
15a80 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 ther [SQLITE_ENA
15a90 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 20 BLE_MEMSYS3] or
15aa0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d [SQLITE_ENABLE_M
15ab0 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 65 74 75 EMSYS5] and retu
15ac0 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 rns.** [SQLITE_E
15ad0 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65 64 RROR] if invoked
15ae0 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20 5e otherwise..** ^
15af0 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 There are three
15b00 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c arguments to SQL
15b10 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3a ITE_CONFIG_HEAP:
15b20 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c .** An 8-byte al
15b30 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f igned pointer to
15b40 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 the memory,.**
15b50 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
15b60 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 tes in the memor
15b70 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 y buffer, and th
15b80 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 e minimum alloca
15b90 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 tion size..** ^I
15ba0 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e f the first poin
15bb0 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 ter (the memory
15bc0 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c pointer) is NULL
15bd0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 , then SQLite re
15be0 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e verts.** to usin
15bf0 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 g its default me
15c00 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 mory allocator (
15c10 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f the system mallo
15c20 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 c() implementati
15c30 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 on),.** undoing
15c40 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 any prior invoca
15c50 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f tion of [SQLITE_
15c60 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 CONFIG_MALLOC].
15c70 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f ^If the.** memo
15c80 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f ry pointer is no
15c90 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 t NULL then the
15ca0 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f alternative memo
15cb0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 ry.** allocator
15cc0 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 is engaged to ha
15cd0 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 ndle all of SQLi
15ce0 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 tes memory alloc
15cf0 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 ation needs..**
15d00 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 The first pointe
15d10 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f r (the memory po
15d20 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 inter) must be a
15d30 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 ligned to an 8-b
15d40 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 yte.** boundary
15d50 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 or subsequent be
15d60 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 havior of SQLite
15d70 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e will be undefin
15d80 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d ed..** The minim
15d90 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 um allocation si
15da0 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 74 20 ze is capped at
15db0 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 2**12. Reasonabl
15dc0 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 e values.** for
15dd0 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f the minimum allo
15de0 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 cation size are
15df0 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 2**5 through 2**
15e00 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 8.</dd>.**.** [[
15e10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
15e20 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 TEX]] <dt>SQLITE
15e30 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 _CONFIG_MUTEX</d
15e40 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 t>.** <dd> ^(The
15e50 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d SQLITE_CONFIG_M
15e60 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 UTEX option take
15e70 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d s a single argum
15e80 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 0a 2a ent which is a.*
15e90 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 * pointer to an
15ea0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 instance of the
15eb0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d [sqlite3_mutex_m
15ec0 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 ethods] structur
15ed0 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 e..** The argume
15ee0 6e 74 20 73 70 65 63 69 66 69 65 73 20 61 6c 74 nt specifies alt
15ef0 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 ernative low-lev
15f00 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 el mutex routine
15f10 73 20 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a 20 s to be used.**
15f20 69 6e 20 70 6c 61 63 65 20 74 68 65 20 6d 75 74 in place the mut
15f30 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c ex routines buil
15f40 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e t into SQLite.)^
15f50 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 ^SQLite makes
15f60 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 a copy of.** the
15f70 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 content of the
15f80 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d [sqlite3_mutex_m
15f90 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 ethods] structur
15fa0 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c e before the cal
15fb0 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 l to.** [sqlite3
15fc0 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 _config()] retur
15fd0 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 ns. ^If SQLite i
15fe0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a s compiled with.
15ff0 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 ** the [SQLITE_T
16000 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 HREADSAFE | SQLI
16010 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d TE_THREADSAFE=0]
16020 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
16030 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 tion then.** the
16040 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 entire mutexing
16050 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d subsystem is om
16060 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 itted from the b
16070 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 uild and hence c
16080 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 alls to.** [sqli
16090 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 te3_config()] wi
160a0 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f th the SQLITE_CO
160b0 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 NFIG_MUTEX confi
160c0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 guration option
160d0 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b will.** return [
160e0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f SQLITE_ERROR].</
160f0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
16100 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 TE_CONFIG_GETMUT
16110 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f EX]] <dt>SQLITE_
16120 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c CONFIG_GETMUTEX<
16130 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 /dt>.** <dd> ^(T
16140 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
16150 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 69 6f 6e _GETMUTEX option
16160 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 takes a single
16170 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a argument which.*
16180 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 * is a pointer t
16190 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 o an instance of
161a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 the [sqlite3_mu
161b0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 tex_methods] str
161c0 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 ucture. The.**
161d0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d [sqlite3_mutex_m
161e0 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 ethods].** struc
161f0 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 ture is filled w
16200 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c ith the currentl
16210 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 y defined mutex
16220 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 routines.)^.** T
16230 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 his option can b
16240 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f e used to overlo
16250 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d ad the default m
16260 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a utex allocation.
16270 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 ** routines with
16280 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20 a wrapper used
16290 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 to track mutex u
162a0 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d sage for perform
162b0 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e ance.** profilin
162c0 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f g or testing, fo
162d0 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 r example. ^If
162e0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
162f0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 led with.** the
16300 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 [SQLITE_THREADSA
16310 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 FE | SQLITE_THRE
16320 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c ADSAFE=0] compil
16330 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 e-time option th
16340 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 en.** the entire
16350 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 mutexing subsys
16360 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 tem is omitted f
16370 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e rom the build an
16380 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f d hence calls to
16390 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e .** [sqlite3_con
163a0 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 fig()] with the
163b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
163c0 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 TMUTEX configura
163d0 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c tion option will
163e0 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 .** return [SQLI
163f0 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a TE_ERROR].</dd>.
16400 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
16410 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d ONFIG_LOOKASIDE]
16420 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
16430 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 FIG_LOOKASIDE</d
16440 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 t>.** <dd> ^(The
16450 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c SQLITE_CONFIG_L
16460 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e 20 OOKASIDE option
16470 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 takes two argume
16480 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 nts that determi
16490 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c ne.** the defaul
164a0 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73 t size of lookas
164b0 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65 61 ide memory on ea
164c0 63 68 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ch [database con
164d0 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 nection]..** The
164e0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
164f0 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f is the.** size o
16500 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 f each lookaside
16510 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 buffer slot and
16520 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 the second is t
16530 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 he number of.**
16540 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 slots allocated
16550 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 to each database
16560 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 connection.)^
16570 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f ^(SQLITE_CONFIG_
16580 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65 74 LOOKASIDE.** set
16590 73 20 74 68 65 20 3c 69 3e 64 65 66 61 75 6c 74 s the <i>default
165a0 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 </i> lookaside s
165b0 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 ize. The [SQLITE
165c0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 _DBCONFIG_LOOKAS
165d0 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74 IDE].** option t
165e0 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f o [sqlite3_db_co
165f0 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 nfig()] can be u
16600 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 sed to change th
16610 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 e lookaside.** c
16620 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 onfiguration on
16630 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 individual conne
16640 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a ctions.)^ </dd>.
16650 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
16660 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 ONFIG_PCACHE2]]
16670 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
16680 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a G_PCACHE2</dt>.*
16690 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c * <dd> ^(The SQL
166a0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 ITE_CONFIG_PCACH
166b0 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 E2 option takes
166c0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e a single argumen
166d0 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 t which is .** a
166e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b pointer to an [
166f0 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d sqlite3_pcache_m
16700 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e ethods2] object.
16710 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 This object sp
16720 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 69 ecifies.** the i
16730 6e 74 65 72 66 61 63 65 20 74 6f 20 61 20 63 75 nterface to a cu
16740 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 stom page cache
16750 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 implementation.)
16760 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61 6b ^.** ^SQLite mak
16770 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 es a copy of the
16780 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 [sqlite3_pcache
16790 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 _methods2] objec
167a0 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b t.</dd>.**.** [[
167b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
167c0 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 TPCACHE2]] <dt>S
167d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
167e0 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 PCACHE2</dt>.**
167f0 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 <dd> ^(The SQLIT
16800 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 E_CONFIG_GETPCAC
16810 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 HE2 option takes
16820 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 a single argume
16830 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 nt which.** is a
16840 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b pointer to an [
16850 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d sqlite3_pcache_m
16860 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e ethods2] object.
16870 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 SQLite copies
16880 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 72 65 6e of.** the curren
16890 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 t page cache imp
168a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f lementation into
168b0 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 that object.)^
168c0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
168d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d LITE_CONFIG_LOG]
168e0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
168f0 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 FIG_LOG</dt>.**
16900 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f <dd> The SQLITE_
16910 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f CONFIG_LOG optio
16920 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e n is used to con
16930 66 69 67 75 72 65 20 74 68 65 20 53 51 4c 69 74 figure the SQLit
16940 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 e.** global [err
16950 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 or log]..** (^Th
16960 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
16970 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 LOG option takes
16980 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 two arguments:
16990 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a a pointer to a.*
169a0 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 * function with
169b0 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 a call signature
169c0 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 of void(*)(void
169d0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 *,int,const char
169e0 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f *), .** and a po
169f0 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e inter to void. ^
16a00 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 If the function
16a10 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e pointer is not N
16a20 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e ULL, it is.** in
16a30 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 voked by [sqlite
16a40 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 3_log()] to proc
16a50 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 ess each logging
16a60 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 event. ^If the
16a70 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 .** function poi
16a80 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 nter is NULL, th
16a90 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 e [sqlite3_log()
16aa0 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f ] interface beco
16ab0 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 mes a no-op..**
16ac0 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 ^The void pointe
16ad0 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65 r that is the se
16ae0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f cond argument to
16af0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c SQLITE_CONFIG_L
16b00 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 OG is.** passed
16b10 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 through as the f
16b20 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 irst parameter t
16b30 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f o the applicatio
16b40 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 n-defined logger
16b50 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 .** function whe
16b60 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 never that funct
16b70 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 ion is invoked.
16b80 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 ^The second par
16b90 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 ameter to.** the
16ba0 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e logger function
16bb0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 is a copy of th
16bc0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
16bd0 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 r to the corresp
16be0 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 onding.** [sqlit
16bf0 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 e3_log()] call a
16c00 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 nd is intended t
16c10 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 o be a [result c
16c20 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 ode] or an.** [e
16c30 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
16c40 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 ode]. ^The thir
16c50 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 d parameter pass
16c60 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 ed to the logger
16c70 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 is.** log messa
16c80 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 ge after formatt
16c90 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 ing via [sqlite3
16ca0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a _snprintf()]..**
16cb0 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 The SQLite logg
16cc0 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 ing interface is
16cd0 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 not reentrant;
16ce0 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 the logger funct
16cf0 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 ion.** supplied
16d00 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 by the applicati
16d10 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f on must not invo
16d20 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e ke any SQLite in
16d30 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 terface..** In a
16d40 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 multi-threaded
16d50 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 application, the
16d60 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
16d70 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 ined logger.** f
16d80 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 unction must be
16d90 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 threadsafe. </dd
16da0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
16db0 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 _CONFIG_URI]] <d
16dc0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
16dd0 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 URI.** <dd>^(The
16de0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 SQLITE_CONFIG_U
16df0 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 RI option takes
16e00 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e a single argumen
16e10 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a 2a t of type int..*
16e20 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 * If non-zero, t
16e30 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 hen URI handling
16e40 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 is globally ena
16e50 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 bled. If the par
16e60 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 0a ameter is zero,.
16e70 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 ** then URI hand
16e80 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 ling is globally
16e90 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 disabled.)^ ^If
16ea0 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 URI handling is
16eb0 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61 globally.** ena
16ec0 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 bled, all filena
16ed0 6d 65 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 mes passed to [s
16ee0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 qlite3_open()],
16ef0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 [sqlite3_open_v2
16f00 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
16f10 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a _open16()] or.**
16f20 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70 61 specified as pa
16f30 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 rt of [ATTACH] c
16f40 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65 ommands are inte
16f50 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 2c rpreted as URIs,
16f60 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f regardless.** o
16f70 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 f whether or not
16f80 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 the [SQLITE_OPE
16f90 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73 N_URI] flag is s
16fa0 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 et when the data
16fb0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 base.** connecti
16fc0 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49 on is opened. ^I
16fd0 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 f it is globally
16fe0 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e disabled, filen
16ff0 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 ames are.** only
17000 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 interpreted as
17010 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c 49 URIs if the SQLI
17020 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 TE_OPEN_URI flag
17030 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 is set when the
17040 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e .** database con
17050 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 nection is opene
17060 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c 74 2c d. ^(By default,
17070 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 URI handling is
17080 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 globally.** dis
17090 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75 abled. The defau
170a0 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20 lt value may be
170b0 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 changed by compi
170c0 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a ling with the.**
170d0 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 [SQLITE_USE_URI
170e0 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 ] symbol defined
170f0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 .)^.**.** [[SQLI
17100 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 TE_CONFIG_COVERI
17110 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 NG_INDEX_SCAN]]
17120 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
17130 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 G_COVERING_INDEX
17140 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 _SCAN.** <dd>^Th
17150 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
17160 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 COVERING_INDEX_S
17170 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 CAN option takes
17180 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 a single intege
17190 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77 68 r.** argument wh
171a0 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 ich is interpret
171b0 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 20 ed as a boolean
171c0 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 in order to enab
171d0 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a 2a le or disable.**
171e0 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 the use of cove
171f0 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 ring indices for
17200 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e full table scan
17210 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f s in the query o
17220 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68 ptimizer..** ^Th
17230 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e e default settin
17240 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a g is determined.
17250 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 ** by the [SQLIT
17260 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 E_ALLOW_COVERING
17270 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d _INDEX_SCAN] com
17280 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
17290 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 , or is "on".**
172a0 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d if that compile-
172b0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f time option is o
172c0 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 mitted..** The a
172d0 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c bility to disabl
172e0 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 e the use of cov
172f0 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f ering indices fo
17300 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 r full table sca
17310 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65 ns.** is because
17320 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c some incorrectl
17330 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61 y coded legacy a
17340 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 pplications migh
17350 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a t malfunction.**
17360 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 when the optimi
17370 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 zation is enable
17380 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68 d. Providing th
17390 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 e ability to.**
173a0 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69 disable the opti
173b0 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 mization allows
173c0 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 the older, buggy
173d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 application cod
173e0 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 e to work.** wit
173f0 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e hout change even
17400 20 77 69 74 68 20 6e 65 77 65 72 20 76 65 72 73 with newer vers
17410 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a ions of SQLite..
17420 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
17430 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b ONFIG_PCACHE]] [
17440 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 [SQLITE_CONFIG_G
17450 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 ETPCACHE]].** <d
17460 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
17470 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54 PCACHE and SQLIT
17480 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 E_CONFIG_GETPCAC
17490 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 HE.** <dd> These
174a0 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 options are obs
174b0 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 olete and should
174c0 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 not be used by
174d0 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 new code..** The
174e0 79 20 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 y are retained f
174f0 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d or backwards com
17500 70 61 74 69 62 69 6c 69 74 79 20 62 75 74 20 61 patibility but a
17510 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a re now no-ops..*
17520 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b * </dd>.**.** [[
17530 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 SQLITE_CONFIG_SQ
17540 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 LLOG]].** <dt>SQ
17550 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c LITE_CONFIG_SQLL
17560 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f OG.** <dd>This o
17570 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 ption is only av
17580 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74 ailable if sqlit
17590 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 e is compiled wi
175a0 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 th the.** [SQLIT
175b0 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d E_ENABLE_SQLLOG]
175c0 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d pre-processor m
175d0 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 acro defined. Th
175e0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
175f0 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 should.** be a
17600 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e pointer to a fun
17610 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f ction of type vo
17620 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 id(*)(void*,sqli
17630 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a te3*,const char*
17640 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 , int)..** The s
17650 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 econd should be
17660 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e of type (void*).
17670 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 The callback is
17680 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20 invoked by the
17690 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 library.** in th
176a0 72 65 65 20 73 65 70 61 72 61 74 65 20 63 69 72 ree separate cir
176b0 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e cumstances, iden
176c0 74 69 66 69 65 64 20 62 79 20 74 68 65 20 76 61 tified by the va
176d0 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 lue passed as th
176e0 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 e.** fourth para
176f0 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f meter. If the fo
17700 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 urth parameter i
17710 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61 s 0, then the da
17720 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
17730 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 n.** passed as t
17740 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
17750 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e nt has just been
17760 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69 opened. The thi
17770 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 rd argument.** p
17780 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65 oints to a buffe
17790 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 r containing the
177a0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 name of the mai
177b0 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e n database file.
177c0 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 If the.** fourt
177d0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 31 h parameter is 1
177e0 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73 , then the SQL s
177f0 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68 tatement that th
17800 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
17810 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 r.** points to h
17820 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65 as just been exe
17830 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 cuted. Or, if th
17840 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
17850 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a er is 2, then.**
17860 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 the connection
17870 62 65 69 6e 67 20 70 61 73 73 65 64 20 61 73 20 being passed as
17880 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d the second param
17890 65 74 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c eter is being cl
178a0 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 osed. The.** thi
178b0 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 rd parameter is
178c0 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 passed NULL In t
178d0 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20 65 78 his case. An ex
178e0 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 ample of using t
178f0 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 his.** configura
17900 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 tion option can
17910 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65 20 22 be seen in the "
17920 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 test_sqllog.c" s
17930 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a ource file in.**
17940 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 the canonical S
17950 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74 72 65 QLite source tre
17960 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b e.</dd>.**.** [[
17970 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d SQLITE_CONFIG_MM
17980 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 AP_SIZE]].** <dt
17990 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d >SQLITE_CONFIG_M
179a0 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e MAP_SIZE.** <dd>
179b0 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d ^SQLITE_CONFIG_M
179c0 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 74 MAP_SIZE takes t
179d0 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 wo 64-bit intege
179e0 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 r (sqlite3_int64
179f0 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 ) values.** that
17a00 20 61 72 65 20 74 68 65 20 64 65 66 61 75 6c 74 are the default
17a10 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 mmap size limit
17a20 20 28 74 68 65 20 64 65 66 61 75 6c 74 20 73 65 (the default se
17a30 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 tting for.** [PR
17a40 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 AGMA mmap_size])
17a50 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d and the maximum
17a60 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 allowed mmap si
17a70 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 ze limit..** ^Th
17a80 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e e default settin
17a90 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 g can be overrid
17aa0 64 65 6e 20 62 79 20 65 61 63 68 20 64 61 74 61 den by each data
17ab0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
17ac0 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 using.** either
17ad0 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 the [PRAGMA mmap
17ae0 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 _size] command,
17af0 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68 65 0a or by using the.
17b00 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c ** [SQLITE_FCNTL
17b10 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 _MMAP_SIZE] file
17b20 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65 control. ^(The
17b30 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 maximum allowed
17b40 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77 69 mmap size.** wi
17b50 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79 20 74 ll be silently t
17b60 72 75 6e 63 61 74 65 64 20 69 66 20 6e 65 63 65 runcated if nece
17b70 73 73 61 72 79 20 73 6f 20 74 68 61 74 20 69 74 ssary so that it
17b80 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 65 65 64 does not exceed
17b90 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d the.** compile-
17ba0 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 time maximum mma
17bb0 70 20 73 69 7a 65 20 73 65 74 20 62 79 20 74 68 p size set by th
17bc0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 e.** [SQLITE_MAX
17bd0 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 _MMAP_SIZE] comp
17be0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e ile-time option.
17bf0 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65 72 )^.** ^If either
17c00 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 argument to thi
17c10 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 61 s option is nega
17c20 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74 20 tive, then that
17c30 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 argument is.** c
17c40 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63 6f hanged to its co
17c50 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 75 mpile-time defau
17c60 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 lt..**.** [[SQLI
17c70 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f TE_CONFIG_WIN32_
17c80 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 HEAPSIZE]].** <d
17c90 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
17ca0 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a 2a WIN32_HEAPSIZE.*
17cb0 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 * <dd>^The SQLIT
17cc0 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 E_CONFIG_WIN32_H
17cd0 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20 69 EAPSIZE option i
17ce0 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 s only available
17cf0 20 69 66 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a if SQLite is.**
17d00 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57 69 compiled for Wi
17d10 6e 64 6f 77 73 20 77 69 74 68 20 74 68 65 20 5b ndows with the [
17d20 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c SQLITE_WIN32_MAL
17d30 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 LOC] pre-process
17d40 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66 69 or macro.** defi
17d50 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f 4e ned. ^SQLITE_CON
17d60 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 FIG_WIN32_HEAPSI
17d70 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d 62 69 ZE takes a 32-bi
17d80 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 t unsigned integ
17d90 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74 er value.** that
17da0 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 6d specifies the m
17db0 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74 aximum size of t
17dc0 68 65 20 63 72 65 61 74 65 64 20 68 65 61 70 2e he created heap.
17dd0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
17de0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 CONFIG_PCACHE_HD
17df0 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c RSZ]].** <dt>SQL
17e00 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 ITE_CONFIG_PCACH
17e10 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e E_HDRSZ.** <dd>^
17e20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 The SQLITE_CONFI
17e30 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20 6f G_PCACHE_HDRSZ o
17e40 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 ption takes a si
17e50 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 ngle parameter w
17e60 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 hich.** is a poi
17e70 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 nter to an integ
17e80 65 72 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e er and writes in
17e90 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 to that integer
17ea0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 the number of ex
17eb0 74 72 61 0a 2a 2a 20 62 79 74 65 73 20 70 65 72 tra.** bytes per
17ec0 20 70 61 67 65 20 72 65 71 75 69 72 65 64 20 66 page required f
17ed0 6f 72 20 65 61 63 68 20 70 61 67 65 20 69 6e 20 or each page in
17ee0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 [SQLITE_CONFIG_P
17ef0 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 AGECACHE]..** Th
17f00 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65 78 74 72 e amount of extr
17f10 61 20 73 70 61 63 65 20 72 65 71 75 69 72 65 64 a space required
17f20 20 63 61 6e 20 63 68 61 6e 67 65 20 64 65 70 65 can change depe
17f30 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6d nding on the com
17f40 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 67 65 74 piler,.** target
17f50 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 20 53 platform, and S
17f60 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 2e 0a 2a QLite version..*
17f70 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
17f80 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 NFIG_PMASZ]].**
17f90 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
17fa0 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e G_PMASZ.** <dd>^
17fb0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 The SQLITE_CONFI
17fc0 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f 6e 20 74 G_PMASZ option t
17fd0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 akes a single pa
17fe0 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a rameter which.**
17ff0 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 is an unsigned
18000 69 6e 74 65 67 65 72 20 61 6e 64 20 73 65 74 73 integer and sets
18010 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d 20 50 4d the "Minimum PM
18020 41 20 53 69 7a 65 22 20 66 6f 72 20 74 68 65 20 A Size" for the
18030 6d 75 6c 74 69 74 68 72 65 61 64 65 64 0a 2a 2a multithreaded.**
18040 20 73 6f 72 74 65 72 20 74 6f 20 74 68 61 74 20 sorter to that
18050 69 6e 74 65 67 65 72 2e 20 20 54 68 65 20 64 65 integer. The de
18060 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d 20 50 4d fault minimum PM
18070 41 20 53 69 7a 65 20 69 73 20 73 65 74 20 62 79 A Size is set by
18080 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the.** [SQLITE_
18090 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d 20 63 6f SORTER_PMASZ] co
180a0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
180b0 6e 2e 20 20 4e 65 77 20 74 68 72 65 61 64 73 20 n. New threads
180c0 61 72 65 20 6c 61 75 6e 63 68 65 64 0a 2a 2a 20 are launched.**
180d0 74 6f 20 68 65 6c 70 20 77 69 74 68 20 73 6f 72 to help with sor
180e0 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 77 68 65 t operations whe
180f0 6e 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 n multithreaded
18100 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 20 65 6e sorting.** is en
18110 61 62 6c 65 64 20 28 75 73 69 6e 67 20 74 68 65 abled (using the
18120 20 5b 50 52 41 47 4d 41 20 74 68 72 65 61 64 73 [PRAGMA threads
18130 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e 64 20 74 ] command) and t
18140 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e he amount of con
18150 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 73 6f tent.** to be so
18160 72 74 65 64 20 65 78 63 65 65 64 73 20 74 68 65 rted exceeds the
18170 20 70 61 67 65 20 73 69 7a 65 20 74 69 6d 65 73 page size times
18180 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6f 66 20 the minimum of
18190 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 63 the.** [PRAGMA c
181a0 61 63 68 65 5f 73 69 7a 65 5d 20 73 65 74 74 69 ache_size] setti
181b0 6e 67 20 61 6e 64 20 74 68 69 73 20 76 61 6c 75 ng and this valu
181c0 65 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 e..** </dl>.*/.#
181d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
181e0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 NFIG_SINGLETHREA
181f0 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a D 1 /* nil */.
18200 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
18210 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 ONFIG_MULTITHREA
18220 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f D 2 /* nil */
18230 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
18240 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 CONFIG_SERIALIZE
18250 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a D 3 /* nil *
18260 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
18270 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 _CONFIG_MALLOC
18280 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 4 /* sqli
18290 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a te3_mem_methods*
182a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
182b0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c TE_CONFIG_GETMAL
182c0 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 LOC 5 /* sq
182d0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
182e0 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 s* */.#define SQ
182f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 LITE_CONFIG_SCRA
18300 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 TCH 6 /*
18310 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 void*, int sz, i
18320 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 nt N */.#define
18330 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 SQLITE_CONFIG_PA
18340 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f GECACHE 7 /
18350 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c * void*, int sz,
18360 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e int N */.#defin
18370 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
18380 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20 HEAP 8
18390 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e /* void*, int n
183a0 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f Byte, int min */
183b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
183c0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 CONFIG_MEMSTATUS
183d0 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 9 /* boole
183e0 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 an */.#define SQ
183f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 LITE_CONFIG_MUTE
18400 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 X 10 /*
18410 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 sqlite3_mutex_me
18420 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e thods* */.#defin
18430 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
18440 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 GETMUTEX 11
18450 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 /* sqlite3_mute
18460 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a x_methods* */./*
18470 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 previously SQLI
18480 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 TE_CONFIG_CHUNKA
18490 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 LLOC 12 which is
184a0 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 now unused. */
184b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
184c0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 CONFIG_LOOKASIDE
184d0 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 13 /* int i
184e0 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 nt */.#define SQ
184f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 LITE_CONFIG_PCAC
18500 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 HE 14 /*
18510 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 no-op */.#define
18520 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 SQLITE_CONFIG_G
18530 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20 ETPCACHE 15
18540 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 /* no-op */.#def
18550 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
18560 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31 G_LOG 1
18570 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 6 /* xFunc, voi
18580 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 d* */.#define SQ
18590 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 LITE_CONFIG_URI
185a0 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20 17 /*
185b0 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 int */.#define S
185c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 QLITE_CONFIG_PCA
185d0 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a CHE2 18 /*
185e0 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f sqlite3_pcache_
185f0 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 methods2* */.#de
18600 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
18610 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20 20 IG_GETPCACHE2
18620 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 19 /* sqlite3_p
18630 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 cache_methods2*
18640 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
18650 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e E_CONFIG_COVERIN
18660 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 20 G_INDEX_SCAN 20
18670 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 /* int */.#defi
18680 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
18690 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 31 _SQLLOG 21
186a0 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f /* xSqllog, vo
186b0 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 id* */.#define S
186c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 QLITE_CONFIG_MMA
186d0 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f 2a P_SIZE 22 /*
186e0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20 sqlite3_int64,
186f0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f sqlite3_int64 */
18700 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
18710 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 CONFIG_WIN32_HEA
18720 50 53 49 5a 45 20 20 20 20 20 20 32 33 20 20 2f PSIZE 23 /
18730 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23 * int nByte */.#
18740 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
18750 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 NFIG_PCACHE_HDRS
18760 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f 2a 20 Z 24 /*
18770 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66 int *psz */.#def
18780 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
18790 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20 20 20 G_PMASZ
187a0 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75 6e 73 25 /* uns
187b0 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61 20 igned int szPma
187c0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 */../*.** CAPI3R
187d0 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e EF: Database Con
187e0 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 nection Configur
187f0 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a ation Options.**
18800 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 .** These consta
18810 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 nts are the avai
18820 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f lable integer co
18830 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
18840 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 ons that.** can
18850 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 be passed as the
18860 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
18870 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
18880 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e _db_config()] in
18890 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e terface..**.** N
188a0 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ew configuration
188b0 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 options may be
188c0 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 added in future
188d0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 releases of SQLi
188e0 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 te..** Existing
188f0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
18900 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 tions might be d
18910 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 iscontinued. Ap
18920 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 plications.** sh
18930 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 ould check the r
18940 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 eturn code from
18950 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 [sqlite3_db_conf
18960 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 ig()] to make su
18970 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 re that.** the c
18980 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 all worked. ^Th
18990 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f e [sqlite3_db_co
189a0 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 nfig()] interfac
189b0 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a e will return a.
189c0 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 ** non-zero [err
189d0 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 or code] if a di
189e0 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e scontinued or un
189f0 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 supported config
18a00 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a uration option.*
18a10 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a * is invoked..**
18a20 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e .** <dl>.** <dt>
18a30 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
18a40 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a LOOKASIDE</dt>.*
18a50 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 * <dd> ^This opt
18a60 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 ion takes three
18a70 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d additional argum
18a80 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d ents that determ
18a90 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f ine the .** [loo
18aa0 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c kaside memory al
18ab0 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 locator] configu
18ac0 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b ration for the [
18ad0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
18ae0 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 ion]..** ^The fi
18af0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 rst argument (th
18b00 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
18b10 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 r to [sqlite3_db
18b20 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a _config()] is a.
18b30 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 ** pointer to a
18b40 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f memory buffer to
18b50 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 use for lookasi
18b60 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 de memory..** ^T
18b70 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
18b80 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 t after the SQLI
18b90 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b TE_DBCONFIG_LOOK
18ba0 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 ASIDE verb.** ma
18bb0 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 y be NULL in whi
18bc0 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 ch case SQLite w
18bd0 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 ill allocate the
18be0 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 .** lookaside bu
18bf0 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e ffer itself usin
18c00 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f g [sqlite3_mallo
18c10 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e c()]. ^The secon
18c20 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 d argument is th
18c30 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 e.** size of eac
18c40 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 h lookaside buff
18c50 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 er slot. ^The t
18c60 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 hird argument is
18c70 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a the number of.*
18c80 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 * slots. The si
18c90 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 ze of the buffer
18ca0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 in the first ar
18cb0 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 gument must be g
18cc0 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f reater than.** o
18cd0 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 r equal to the p
18ce0 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 roduct of the se
18cf0 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 cond and third a
18d00 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 rguments. The b
18d10 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 uffer.** must be
18d20 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 aligned to an 8
18d30 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 -byte boundary.
18d40 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 ^If the second
18d50 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 argument to.** S
18d60 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c QLITE_DBCONFIG_L
18d70 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 OOKASIDE is not
18d80 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c a multiple of 8,
18d90 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c it is internall
18da0 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 y.** rounded dow
18db0 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d n to the next sm
18dc0 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f aller multiple o
18dd0 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b f 8. ^(The look
18de0 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 aside memory.**
18df0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f configuration fo
18e00 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e r a database con
18e10 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 nection can only
18e20 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e be changed when
18e30 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 that.** connect
18e40 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 ion is not curre
18e50 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 ntly using looka
18e60 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 side memory, or
18e70 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a in other words.*
18e80 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 * when the "curr
18e90 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 ent value" retur
18ea0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 ned by.** [sqlit
18eb0 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c e3_db_status](D,
18ec0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c [SQLITE_CONFIG_L
18ed0 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 OOKASIDE],...) i
18ee0 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 s zero..** Any a
18ef0 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 ttempt to change
18f00 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d the lookaside m
18f10 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 emory configurat
18f20 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 ion when lookasi
18f30 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 de.** memory is
18f40 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 in use leaves th
18f50 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 e configuration
18f60 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 unchanged and re
18f70 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 turns .** [SQLIT
18f80 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a E_BUSY].)^</dd>.
18f90 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
18fa0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 _DBCONFIG_ENABLE
18fb0 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 _FKEY</dt>.** <d
18fc0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 d> ^This option
18fd0 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c is used to enabl
18fe0 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 e or disable the
18ff0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a enforcement of.
19000 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 ** [foreign key
19010 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 constraints]. T
19020 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 here should be t
19030 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 wo additional ar
19040 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 guments..** The
19050 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 first argument i
19060 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 s an integer whi
19070 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 ch is 0 to disab
19080 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e le FK enforcemen
19090 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 t,.** positive t
190a0 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f o enable FK enfo
190b0 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 rcement or negat
190c0 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 ive to leave FK
190d0 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 enforcement.** u
190e0 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 nchanged. The s
190f0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
19100 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
19110 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 an integer into
19120 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 which.** is writ
19130 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e ten 0 or 1 to in
19140 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46 dicate whether F
19150 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 K enforcement is
19160 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f off or on.** fo
19170 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c llowing this cal
19180 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 l. The second p
19190 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 arameter may be
191a0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 a NULL pointer,
191b0 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 in.** which case
191c0 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d the FK enforcem
191d0 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e ent setting is n
191e0 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b ot reported back
191f0 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 . </dd>.**.** <d
19200 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 t>SQLITE_DBCONFI
19210 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 G_ENABLE_TRIGGER
19220 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 </dt>.** <dd> ^T
19230 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 his option is us
19240 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 ed to enable or
19250 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 disable [CREATE
19260 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 TRIGGER | trigge
19270 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 rs]..** There sh
19280 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 ould be two addi
19290 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 tional arguments
192a0 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 ..** The first a
192b0 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e rgument is an in
192c0 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 teger which is 0
192d0 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 to disable trig
192e0 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 gers,.** positiv
192f0 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 e to enable trig
19300 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 gers or negative
19310 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 to leave the se
19320 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e tting unchanged.
19330 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 .** The second p
19340 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f arameter is a po
19350 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 inter to an inte
19360 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a ger into which.*
19370 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f * is written 0 o
19380 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 r 1 to indicate
19390 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73 whether triggers
193a0 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 are disabled or
193b0 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c enabled.** foll
193c0 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e owing this call.
193d0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 The second par
193e0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 ameter may be a
193f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e NULL pointer, in
19400 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 .** which case t
19410 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69 he trigger setti
19420 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 ng is not report
19430 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a ed back. </dd>.*
19440 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 *.** </dl>.*/.#d
19450 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 efine SQLITE_DBC
19460 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 ONFIG_LOOKASIDE
19470 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 1001 /* v
19480 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a oid* int int */.
19490 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
194a0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 BCONFIG_ENABLE_F
194b0 4b 45 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a KEY 1002 /*
194c0 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 int int* */.#de
194d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f fine SQLITE_DBCO
194e0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 NFIG_ENABLE_TRIG
194f0 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e GER 1003 /* in
19500 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a t int* */.../*.*
19510 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 * CAPI3REF: Enab
19520 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 le Or Disable Ex
19530 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f tended Result Co
19540 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 des.** METHOD: s
19550 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 qlite3.**.** ^Th
19560 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 e sqlite3_extend
19570 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 ed_result_codes(
19580 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 ) routine enable
19590 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 s or disables th
195a0 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 e.** [extended r
195b0 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 esult codes] fea
195c0 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 ture of SQLite.
195d0 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 ^The extended re
195e0 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 sult.** codes ar
195f0 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 e disabled by de
19600 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 fault for histor
19610 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 ical compatibili
19620 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 ty..*/.SQLITE_AP
19630 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
19640 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 78 74 CALL sqlite3_ext
19650 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 ended_result_cod
19660 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 es(sqlite3*, int
19670 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 onoff);../*.**
19680 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 CAPI3REF: Last I
19690 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 20 4d nsert Rowid.** M
196a0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a ETHOD: sqlite3.*
196b0 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 *.** ^Each entry
196c0 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65 20 in most SQLite
196d0 74 61 62 6c 65 73 20 28 65 78 63 65 70 74 20 66 tables (except f
196e0 6f 72 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 or [WITHOUT ROWI
196f0 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68 61 D] tables).** ha
19700 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 s a unique 64-bi
19710 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 t signed.** inte
19720 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 ger key called t
19730 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 he [ROWID | "row
19740 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 id"]. ^The rowid
19750 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c is always avail
19760 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e able.** as an un
19770 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 declared column
19780 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 named ROWID, OID
19790 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 , or _ROWID_ as
197a0 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a long as those.**
197b0 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 names are not a
197c0 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c lso used by expl
197d0 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 icitly declared
197e0 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 columns. ^If.**
197f0 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 the table has a
19800 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b column of type [
19810 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 INTEGER PRIMARY
19820 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63 KEY] then that c
19830 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 olumn.** is anot
19840 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 her alias for th
19850 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e e rowid..**.** ^
19860 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 The sqlite3_last
19870 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 _insert_rowid(D)
19880 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
19890 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f ns the [rowid] o
198a0 66 20 74 68 65 20 0a 2a 2a 20 6d 6f 73 74 20 72 f the .** most r
198b0 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c ecent successful
198c0 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 [INSERT] into a
198d0 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20 rowid table or
198e0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a [virtual table].
198f0 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63 ** on database c
19900 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 20 onnection D..**
19910 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57 ^Inserts into [W
19920 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 ITHOUT ROWID] ta
19930 62 6c 65 73 20 61 72 65 20 6e 6f 74 20 72 65 63 bles are not rec
19940 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e 6f orded..** ^If no
19950 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 successful [INS
19960 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64 ERT]s into rowid
19970 20 74 61 62 6c 65 73 0a 2a 2a 20 68 61 76 65 20 tables.** have
19980 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e ever occurred on
19990 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
199a0 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a 20 nnection D, .**
199b0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73 then sqlite3_las
199c0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 t_insert_rowid(D
199d0 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a ) returns zero..
199e0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 **.** ^(If an [I
199f0 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 NSERT] occurs wi
19a00 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 6f thin a trigger o
19a10 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72 74 r within a [virt
19a20 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 ual table].** me
19a30 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 20 thod, then this
19a40 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 routine will ret
19a50 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 urn the [rowid]
19a60 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a of the inserted.
19a70 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 ** row as long a
19a80 73 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 s the trigger or
19a90 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d virtual table m
19aa0 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67 ethod is running
19ab0 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 ..** But once th
19ac0 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 e trigger or vir
19ad0 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f tual table metho
19ae0 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 d ends, the valu
19af0 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 e returned .** b
19b00 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 y this routine r
19b10 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 20 69 everts to what i
19b20 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 68 65 t was before the
19b30 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 trigger or virt
19b40 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74 ual.** table met
19b50 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a hod began.)^.**.
19b60 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 ** ^An [INSERT]
19b70 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 that fails due t
19b80 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 o a constraint v
19b90 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 iolation is not
19ba0 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 a.** successful
19bb0 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 [INSERT] and doe
19bc0 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 s not change the
19bd0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
19be0 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 by this.** routi
19bf0 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 ne. ^Thus INSER
19c00 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 T OR FAIL, INSER
19c10 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 T OR IGNORE, INS
19c20 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c ERT OR ROLLBACK,
19c30 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f .** and INSERT O
19c40 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 R ABORT make no
19c50 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 changes to the r
19c60 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 eturn value of t
19c70 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 his.** routine w
19c80 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 hen their insert
19c90 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 ion fails. ^(Wh
19ca0 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 en INSERT OR REP
19cb0 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 LACE.** encounte
19cc0 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 rs a constraint
19cd0 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f violation, it do
19ce0 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 es not fail. Th
19cf0 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 e.** INSERT cont
19d00 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 inues to complet
19d10 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 ion after deleti
19d20 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 ng rows that cau
19d30 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 sed.** the const
19d40 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f raint problem so
19d50 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 INSERT OR REPLA
19d60 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 CE will always c
19d70 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 hange.** the ret
19d80 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 urn value of thi
19d90 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a s interface.)^.*
19da0 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 *.** ^For the pu
19db0 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 rposes of this r
19dc0 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 outine, an [INSE
19dd0 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 RT] is considere
19de0 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 d to.** be succe
19df0 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 ssful even if it
19e00 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 is subsequently
19e10 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a rolled back..**
19e20 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f .** This functio
19e30 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 n is accessible
19e40 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 to SQL statement
19e50 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 s via the.** [la
19e60 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 st_insert_rowid(
19e70 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e ) SQL function].
19e80 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 .**.** If a sepa
19e90 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66 rate thread perf
19ea0 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 orms a new [INSE
19eb0 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a RT] on the same.
19ec0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ** database conn
19ed0 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 ection while the
19ee0 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 [sqlite3_last_i
19ef0 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a nsert_rowid()].*
19f00 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 * function is ru
19f10 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 nning and thus c
19f20 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 hanges the last
19f30 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a insert [rowid],.
19f40 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 ** then the valu
19f50 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 e returned by [s
19f60 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 qlite3_last_inse
19f70 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a rt_rowid()] is.*
19f80 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 * unpredictable
19f90 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 and might not eq
19fa0 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f ual either the o
19fb0 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a ld or the new.**
19fc0 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f last insert [ro
19fd0 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f wid]..*/.SQLITE_
19fe0 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 API sqlite3_int6
19ff0 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 4 SQLITE_STDCALL
1a000 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e sqlite3_last_in
1a010 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 sert_rowid(sqlit
1a020 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 e3*);../*.** CAP
1a030 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 I3REF: Count The
1a040 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 Number Of Rows
1a050 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 Modified.** METH
1a060 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a OD: sqlite3.**.*
1a070 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e * ^This function
1a080 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
1a090 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 ber of rows modi
1a0a0 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f fied, inserted o
1a0b0 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 r.** deleted by
1a0c0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c the most recentl
1a0d0 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 y completed INSE
1a0e0 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 RT, UPDATE or DE
1a0f0 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e LETE.** statemen
1a100 74 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 t on the databas
1a110 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 e connection spe
1a120 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e cified by the on
1a130 6c 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a ly parameter..**
1a140 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 ^Executing any
1a150 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 other type of SQ
1a160 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 L statement does
1a170 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 not modify the
1a180 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 value.** returne
1a190 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 d by this functi
1a1a0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 on..**.** ^Only
1a1b0 63 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72 changes made dir
1a1c0 65 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53 ectly by the INS
1a1d0 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 ERT, UPDATE or D
1a1e0 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 ELETE statement
1a1f0 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 are.** considere
1a200 64 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68 d - auxiliary ch
1a210 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 anges caused by
1a220 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 [CREATE TRIGGER
1a230 7c 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a | triggers], .**
1a240 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 [foreign key ac
1a250 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 tions] or [REPLA
1a260 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 CE] constraint r
1a270 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f esolution are no
1a280 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a t counted..** .*
1a290 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 * Changes to a v
1a2a0 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 iew that are int
1a2b0 65 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 ercepted by .**
1a2c0 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 [INSTEAD OF trig
1a2d0 67 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 ger | INSTEAD OF
1a2e0 20 74 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e triggers] are n
1a2f0 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 ot counted. ^The
1a300 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 value .** retur
1a310 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 ned by sqlite3_c
1a320 68 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61 hanges() immedia
1a330 74 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e tely after an IN
1a340 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 SERT, UPDATE or
1a350 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65 .** DELETE state
1a360 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 ment run on a vi
1a370 65 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 ew is always zer
1a380 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 o. Only changes
1a390 6d 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a made to real .**
1a3a0 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e tables are coun
1a3b0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 ted..**.** Thing
1a3c0 73 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c s are more compl
1a3d0 69 63 61 74 65 64 20 69 66 20 74 68 65 20 73 71 icated if the sq
1a3e0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 lite3_changes()
1a3f0 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 function is.** e
1a400 78 65 63 75 74 65 64 20 77 68 69 6c 65 20 61 20 xecuted while a
1a410 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 trigger program
1a420 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 is running. This
1a430 20 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20 74 may happen if t
1a440 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 he.** program us
1a450 65 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 es the [changes(
1a460 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c ) SQL function],
1a470 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 or if some othe
1a480 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 r callback.** fu
1a490 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 nction invokes s
1a4a0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 qlite3_changes()
1a4b0 20 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e directly. Essen
1a4c0 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c tially:.** .** <
1a4d0 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 ul>.** <li> ^(
1a4e0 42 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 Before entering
1a4f0 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 a trigger progra
1a500 6d 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 m the value retu
1a510 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 rned by.**
1a520 20 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 sqlite3_change
1a530 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 s() function is
1a540 73 61 76 65 64 2e 20 41 66 74 65 72 20 74 68 65 saved. After the
1a550 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d trigger program
1a560 20 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20 .** has
1a570 66 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72 finished, the or
1a580 69 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 iginal value is
1a590 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a restored.)^.** .
1a5a0 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 ** <li> ^(With
1a5b0 69 6e 20 61 20 74 72 69 67 67 65 72 20 70 72 6f in a trigger pro
1a5c0 67 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54 gram each INSERT
1a5d0 2c 20 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c , UPDATE and DEL
1a5e0 45 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 ETE .** s
1a5f0 74 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68 tatement sets th
1a600 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
1a610 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e by sqlite3_chan
1a620 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 ges() .**
1a630 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e upon completion
1a640 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 as normal. Of c
1a650 6f 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75 ourse, this valu
1a660 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 e will not inclu
1a670 64 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e de .** an
1a680 79 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72 y changes perfor
1a690 6d 65 64 20 62 79 20 73 75 62 2d 74 72 69 67 67 med by sub-trigg
1a6a0 65 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69 ers, as the sqli
1a6b0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a te3_changes() .*
1a6c0 2a 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 77 * value w
1a6d0 69 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64 ill be saved and
1a6e0 20 72 65 73 74 6f 72 65 64 20 61 66 74 65 72 20 restored after
1a6f0 65 61 63 68 20 73 75 62 2d 74 72 69 67 67 65 72 each sub-trigger
1a700 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c has run.)^.** <
1a710 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 /ul>.** .** ^Thi
1a720 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20 s means that if
1a730 74 68 65 20 63 68 61 6e 67 65 73 28 29 20 53 51 the changes() SQ
1a740 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 L function (or s
1a750 69 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a imilar) is used.
1a760 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73 74 20 ** by the first
1a770 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f INSERT, UPDATE o
1a780 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 r DELETE stateme
1a790 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 nt within a trig
1a7a0 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 ger, it .** retu
1a7b0 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61 73 rns the value as
1a7c0 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 63 61 set when the ca
1a7d0 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 lling statement
1a7e0 62 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e began executing.
1a7f0 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73 .** ^If it is us
1a800 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 ed by the second
1a810 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 73 or subsequent s
1a820 75 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69 uch statement wi
1a830 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a thin a trigger .
1a840 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 ** program, the
1a850 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72 value returned r
1a860 65 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62 eflects the numb
1a870 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 er of rows modif
1a880 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 ied by the .** p
1a890 72 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 revious INSERT,
1a8a0 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 UPDATE or DELETE
1a8b0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 statement withi
1a8c0 6e 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 n the same trigg
1a8d0 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c er..**.** See al
1a8e0 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f so the [sqlite3_
1a8f0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d total_changes()]
1a900 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a interface, the.
1a910 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 ** [count_change
1a920 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 s pragma], and t
1a930 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 he [changes() SQ
1a940 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a L function]..**.
1a950 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 ** If a separate
1a960 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 thread makes ch
1a970 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d anges on the sam
1a980 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
1a990 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b ction.** while [
1a9a0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 sqlite3_changes(
1a9b0 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 )] is running th
1a9c0 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 en the value ret
1a9d0 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 urned.** is unpr
1a9e0 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f edictable and no
1a9f0 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f t meaningful..*/
1aa00 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
1aa10 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
1aa20 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 qlite3_changes(s
1aa30 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a qlite3*);../*.**
1aa40 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c CAPI3REF: Total
1aa50 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 Number Of Rows
1aa60 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 Modified.** METH
1aa70 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a OD: sqlite3.**.*
1aa80 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e * ^This function
1aa90 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74 returns the tot
1aaa0 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 al number of row
1aab0 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64 69 s inserted, modi
1aac0 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 fied or.** delet
1aad0 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45 52 ed by all [INSER
1aae0 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 T], [UPDATE] or
1aaf0 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 [DELETE] stateme
1ab00 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a nts completed.**
1ab10 20 73 69 6e 63 65 20 74 68 65 20 64 61 74 61 62 since the datab
1ab20 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 ase connection w
1ab30 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c 75 as opened, inclu
1ab40 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65 63 75 ding those execu
1ab50 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f ted as.** part o
1ab60 66 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 f trigger progra
1ab70 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67 20 61 ms. ^Executing a
1ab80 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 ny other type of
1ab90 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a SQL statement.*
1aba0 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66 65 63 * does not affec
1abb0 74 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 t the value retu
1abc0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f rned by sqlite3_
1abd0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 2e total_changes().
1abe0 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 .** .** ^Changes
1abf0 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 made as part of
1ac00 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 [foreign key ac
1ac10 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c 75 tions] are inclu
1ac20 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63 6f ded in the.** co
1ac30 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65 20 6d unt, but those m
1ac40 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20 52 ade as part of R
1ac50 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e EPLACE constrain
1ac60 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 t resolution are
1ac70 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67 65 .** not. ^Change
1ac80 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 s to a view that
1ac90 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65 64 are intercepted
1aca0 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46 20 74 by INSTEAD OF t
1acb0 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72 65 20 riggers .** are
1acc0 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 not counted..**
1acd0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 .** See also the
1ace0 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 [sqlite3_change
1acf0 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 s()] interface,
1ad00 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 the.** [count_ch
1ad10 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 anges pragma], a
1ad20 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 nd the [total_ch
1ad30 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 anges() SQL func
1ad40 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 tion]..**.** If
1ad50 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 a separate threa
1ad60 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 d makes changes
1ad70 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 on the same data
1ad80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a base connection.
1ad90 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 ** while [sqlite
1ada0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 3_total_changes(
1adb0 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 )] is running th
1adc0 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 en the value.**
1add0 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 returned is unpr
1ade0 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f edictable and no
1adf0 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f t meaningful..*/
1ae00 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
1ae10 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
1ae20 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 qlite3_total_cha
1ae30 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a nges(sqlite3*);.
1ae40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1ae50 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e Interrupt A Lon
1ae60 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a g-Running Query.
1ae70 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
1ae80 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 e3.**.** ^This f
1ae90 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 unction causes a
1aea0 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 ny pending datab
1aeb0 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f ase operation to
1aec0 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 abort and.** re
1aed0 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c turn at its earl
1aee0 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 iest opportunity
1aef0 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 . This routine i
1af00 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 s typically.** c
1af10 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 alled in respons
1af20 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 e to a user acti
1af30 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73 on such as press
1af40 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 ing "Cancel".**
1af50 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 or Ctrl-C where
1af60 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 the user wants a
1af70 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 long query oper
1af80 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a ation to halt.**
1af90 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a immediately..**
1afa0 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20 .** ^It is safe
1afb0 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 to call this rou
1afc0 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 tine from a thre
1afd0 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f ad different fro
1afe0 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 m the.** thread
1aff0 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c that is currentl
1b000 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 y running the da
1b010 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e tabase operation
1b020 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 . But it.** is
1b030 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c not safe to call
1b040 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 this routine wi
1b050 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 th a [database c
1b060 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a onnection] that.
1b070 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 ** is closed or
1b080 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f might close befo
1b090 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 re sqlite3_inter
1b0a0 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a rupt() returns..
1b0b0 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c **.** ^If an SQL
1b0c0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 operation is ve
1b0d0 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 ry nearly finish
1b0e0 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 ed at the time w
1b0f0 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 hen.** sqlite3_i
1b100 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61 nterrupt() is ca
1b110 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 lled, then it mi
1b120 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 ght not have an
1b130 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 opportunity.** t
1b140 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 o be interrupted
1b150 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 and might conti
1b160 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f nue to completio
1b170 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c n..**.** ^An SQL
1b180 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 operation that
1b190 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 is interrupted w
1b1a0 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 ill return [SQLI
1b1b0 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a TE_INTERRUPT]..*
1b1c0 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72 * ^If the interr
1b1d0 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 upted SQL operat
1b1e0 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 ion is an INSERT
1b1f0 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c , UPDATE, or DEL
1b200 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 ETE.** that is i
1b210 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 nside an explici
1b220 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 t transaction, t
1b230 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 hen the entire t
1b240 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 ransaction.** wi
1b250 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 ll be rolled bac
1b260 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e k automatically.
1b270 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
1b280 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 te3_interrupt(D)
1b290 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 call is in effe
1b2a0 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 ct until all cur
1b2b0 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a rently running.*
1b2c0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 * SQL statements
1b2d0 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f on [database co
1b2e0 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 nnection] D comp
1b2f0 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 lete. ^Any new
1b300 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a SQL statements.*
1b310 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 * that are start
1b320 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c ed after the sql
1b330 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
1b340 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 call and before
1b350 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 the .** running
1b360 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63 statements reac
1b370 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 hes zero are int
1b380 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20 74 errupted as if t
1b390 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 hey had been.**
1b3a0 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f running prior to
1b3b0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 the sqlite3_int
1b3c0 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 errupt() call.
1b3d0 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 ^New SQL stateme
1b3e0 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 nts.** that are
1b3f0 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 started after th
1b400 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d e running statem
1b410 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 ent count reache
1b420 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f s zero are.** no
1b430 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68 t effected by th
1b440 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 e sqlite3_interr
1b450 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c upt()..** ^A cal
1b460 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 l to sqlite3_int
1b470 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20 6f errupt(D) that o
1b480 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 65 ccurs when there
1b490 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a are no running.
1b4a0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ** SQL statement
1b4b0 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 s is a no-op and
1b4c0 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f has no effect o
1b4d0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 n SQL statements
1b4e0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 .** that are sta
1b4f0 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 rted after the s
1b500 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
1b510 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e () call returns.
1b520 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 .**.** If the da
1b530 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1b540 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b n closes while [
1b550 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
1b560 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 t()].** is runni
1b570 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e ng then bad thin
1b580 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 gs will likely h
1b590 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 appen..*/.SQLITE
1b5a0 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45 _API void SQLITE
1b5b0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
1b5c0 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 _interrupt(sqlit
1b5d0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 e3*);../*.** CAP
1b5e0 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 I3REF: Determine
1b5f0 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 If An SQL State
1b600 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 ment Is Complete
1b610 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
1b620 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c tines are useful
1b630 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d during command-
1b640 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 line input to de
1b650 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a termine if the.*
1b660 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 * currently ente
1b670 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 red text seems t
1b680 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 o form a complet
1b690 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
1b6a0 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f or.** if additio
1b6b0 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 nal input is nee
1b6c0 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 ded before sendi
1b6d0 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f ng the text into
1b6e0 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 .** SQLite for p
1b6f0 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 arsing. ^These
1b700 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
1b710 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 1 if the input s
1b720 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 tring.** appears
1b730 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 to be a complet
1b740 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e e SQL statement.
1b750 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 ^A statement i
1b760 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a s judged to be.*
1b770 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 * complete if it
1b780 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d ends with a sem
1b790 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 icolon token and
1b7a0 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 is not a prefix
1b7b0 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f of a.** well-fo
1b7c0 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47 rmed CREATE TRIG
1b7d0 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 GER statement.
1b7e0 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 ^Semicolons that
1b7f0 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 are embedded wi
1b800 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c thin.** string l
1b810 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 iterals or quote
1b820 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d d identifier nam
1b830 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 es or comments a
1b840 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 re not.** indepe
1b850 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 ndent tokens (th
1b860 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 ey are part of t
1b870 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 he token in whic
1b880 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d h they are.** em
1b890 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 bedded) and thus
1b8a0 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 do not count as
1b8b0 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 a statement ter
1b8c0 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 minator. ^White
1b8d0 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d space.** and com
1b8e0 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f ments that follo
1b8f0 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 w the final semi
1b900 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 colon are ignore
1b910 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 d..**.** ^These
1b920 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
1b930 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 0 if the stateme
1b940 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 nt is incomplete
1b950 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f . ^If a.** memo
1b960 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 ry allocation fa
1b970 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 ils, then SQLITE
1b980 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e _NOMEM is return
1b990 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 ed..**.** ^These
1b9a0 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 routines do not
1b9b0 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 parse the SQL s
1b9c0 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a tatements thus.*
1b9d0 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 * will not detec
1b9e0 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 t syntactically
1b9f0 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a incorrect SQL..*
1ba00 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 *.** ^(If SQLite
1ba10 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e has not been in
1ba20 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 itialized using
1ba30 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c [sqlite3_initial
1ba40 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a ize()] prior .**
1ba50 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c to invoking sql
1ba60 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 ite3_complete16(
1ba70 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 ) then sqlite3_i
1ba80 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 nitialize() is i
1ba90 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 nvoked.** automa
1baa0 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 tically by sqlit
1bab0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e e3_complete16().
1bac0 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 If that initia
1bad0 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a lization fails,.
1bae0 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 ** then the retu
1baf0 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 rn value from sq
1bb00 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 lite3_complete16
1bb10 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a () will be non-z
1bb20 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 ero.** regardles
1bb30 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 s of whether or
1bb40 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 not the input SQ
1bb50 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e L is complete.)^
1bb60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 .**.** The input
1bb70 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d to [sqlite3_com
1bb80 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 plete()] must be
1bb90 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 a zero-terminat
1bba0 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 ed.** UTF-8 stri
1bbb0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e ng..**.** The in
1bbc0 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f put to [sqlite3_
1bbd0 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 complete16()] mu
1bbe0 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 st be a zero-ter
1bbf0 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 minated.** UTF-1
1bc00 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 6 string in nati
1bc10 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a ve byte order..*
1bc20 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
1bc30 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
1bc40 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 sqlite3_complete
1bc50 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c (const char *sql
1bc60 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
1bc70 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
1bc80 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 sqlite3_complet
1bc90 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a e16(const void *
1bca0 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 sql);../*.** CAP
1bcb0 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 I3REF: Register
1bcc0 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 A Callback To Ha
1bcd0 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 ndle SQLITE_BUSY
1bce0 20 45 72 72 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f Errors.** KEYWO
1bcf0 52 44 53 3a 20 7b 62 75 73 79 2d 68 61 6e 64 6c RDS: {busy-handl
1bd00 65 72 20 63 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 er callback} {bu
1bd10 73 79 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d sy handler}.** M
1bd20 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a ETHOD: sqlite3.*
1bd30 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
1bd40 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 3_busy_handler(D
1bd50 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65 20 73 65 ,X,P) routine se
1bd60 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 ts a callback fu
1bd70 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 nction X.** that
1bd80 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 might be invoke
1bd90 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 d with argument
1bda0 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e P whenever.** an
1bdb0 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 attempt is made
1bdc0 20 74 6f 20 61 63 63 65 73 73 20 61 20 64 61 74 to access a dat
1bdd0 61 62 61 73 65 20 74 61 62 6c 65 20 61 73 73 6f abase table asso
1bde0 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b ciated with.** [
1bdf0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1be00 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74 ion] D when anot
1be10 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 her thread.** or
1be20 20 70 72 6f 63 65 73 73 20 68 61 73 20 74 68 65 process has the
1be30 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a table locked..*
1be40 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75 * The sqlite3_bu
1be50 73 79 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e 74 sy_handler() int
1be60 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 erface is used t
1be70 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b o implement.** [
1be80 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d sqlite3_busy_tim
1be90 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50 52 41 eout()] and [PRA
1bea0 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 GMA busy_timeout
1beb0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 ]..**.** ^If the
1bec0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 busy callback i
1bed0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 s NULL, then [SQ
1bee0 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 LITE_BUSY].** is
1bef0 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 returned immedi
1bf00 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 ately upon encou
1bf10 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b ntering the lock
1bf20 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 . ^If the busy
1bf30 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e callback.** is n
1bf40 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 ot NULL, then th
1bf50 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 e callback might
1bf60 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 be invoked with
1bf70 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a two arguments..
1bf80 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 **.** ^The first
1bf90 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
1bfa0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 busy handler is
1bfb0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 a copy of the v
1bfc0 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 oid* pointer whi
1bfd0 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 ch.** is the thi
1bfe0 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 rd argument to s
1bff0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 qlite3_busy_hand
1c000 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 ler(). ^The sec
1c010 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a ond argument to.
1c020 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 ** the busy hand
1c030 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 ler callback is
1c040 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 the number of ti
1c050 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73 mes that the bus
1c060 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a y handler has.**
1c070 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 70 72 been invoked pr
1c080 65 76 69 6f 75 73 6c 79 20 66 6f 72 20 74 68 65 eviously for the
1c090 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 same locking ev
1c0a0 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a ent. ^If the.**
1c0b0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 busy callback r
1c0c0 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e eturns 0, then n
1c0d0 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 o additional att
1c0e0 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 empts are made t
1c0f0 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 o.** access the
1c100 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 database and [SQ
1c110 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 20 72 65 LITE_BUSY] is re
1c120 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65 turned.** to the
1c130 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a application..**
1c140 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 ^If the callbac
1c150 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 k returns non-ze
1c160 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 ro, then another
1c170 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d attempt.** is m
1c180 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 74 68 ade to access th
1c190 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 e database and t
1c1a0 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 he cycle repeats
1c1b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 ..**.** The pres
1c1c0 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 ence of a busy h
1c1d0 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 andler does not
1c1e0 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 guarantee that i
1c1f0 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 t will be invoke
1c200 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 d.** when there
1c210 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 is lock contenti
1c220 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 on. ^If SQLite d
1c230 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 etermines that i
1c240 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 nvoking the busy
1c250 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c .** handler coul
1c260 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 d result in a de
1c270 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 adlock, it will
1c280 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 go ahead and ret
1c290 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 urn [SQLITE_BUSY
1c2a0 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c ].** to the appl
1c2b0 69 63 61 74 69 6f 6e 20 69 6e 73 74 65 61 64 20 ication instead
1c2c0 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 of invoking the
1c2d0 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 .** busy handler
1c2e0 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 ..** Consider a
1c2f0 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f scenario where o
1c300 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f ne process is ho
1c310 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 lding a read loc
1c320 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 k that.** it is
1c330 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 trying to promot
1c340 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 e to a reserved
1c350 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 lock and.** a se
1c360 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 cond process is
1c370 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 holding a reserv
1c380 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 ed lock that it
1c390 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 is trying.** to
1c3a0 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 promote to an ex
1c3b0 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 clusive lock. T
1c3c0 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 he first process
1c3d0 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a cannot proceed.
1c3e0 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73 ** because it is
1c3f0 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 blocked by the
1c400 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 second and the s
1c410 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 econd process ca
1c420 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 nnot.** proceed
1c430 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c because it is bl
1c440 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 ocked by the fir
1c450 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f st. If both pro
1c460 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 cesses.** invoke
1c470 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 the busy handle
1c480 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c rs, neither will
1c490 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 make any progre
1c4a0 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a ss. Therefore,.
1c4b0 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e ** SQLite return
1c4c0 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 s [SQLITE_BUSY]
1c4d0 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72 for the first pr
1c4e0 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 ocess, hoping th
1c4f0 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 at this.** will
1c500 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74 induce the first
1c510 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 process to rele
1c520 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 ase its read loc
1c530 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 k and allow.** t
1c540 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 he second proces
1c550 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a s to proceed..**
1c560 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 .** ^The default
1c570 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 busy callback i
1c580 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 s NULL..**.** ^(
1c590 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 There can only b
1c5a0 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 e a single busy
1c5b0 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 handler defined
1c5c0 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 for each.** [dat
1c5d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1c5e0 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 ]. Setting a ne
1c5f0 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 w busy handler c
1c600 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 lears any.** pre
1c610 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 viously set hand
1c620 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 ler.)^ ^Note th
1c630 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 at calling [sqli
1c640 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 te3_busy_timeout
1c650 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61 ()].** or evalua
1c660 74 69 6e 67 20 5b 50 52 41 47 4d 41 20 62 75 73 ting [PRAGMA bus
1c670 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c y_timeout=N] wil
1c680 6c 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 l change the.**
1c690 62 75 73 79 20 68 61 6e 64 6c 65 72 20 61 6e 64 busy handler and
1c6a0 20 74 68 75 73 20 63 6c 65 61 72 20 61 6e 79 20 thus clear any
1c6b0 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 62 previously set b
1c6c0 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a usy handler..**.
1c6d0 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c ** The busy call
1c6e0 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 back should not
1c6f0 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 take any actions
1c700 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 which modify th
1c710 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f e.** database co
1c720 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e nnection that in
1c730 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 voked the busy h
1c740 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65 andler. In othe
1c750 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20 r words,.** the
1c760 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 busy handler is
1c770 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 20 20 not reentrant.
1c780 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 Any such actions
1c790 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e .** result in un
1c7a0 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 defined behavior
1c7b0 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 ..** .** A busy
1c7c0 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 handler must not
1c7d0 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 close the datab
1c7e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a ase connection.*
1c7f0 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 * or [prepared s
1c800 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 tatement] that i
1c810 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 nvoked the busy
1c820 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49 handler..*/.SQLI
1c830 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
1c840 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
1c850 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 3_busy_handler(s
1c860 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 qlite3*, int(*)(
1c870 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 void*,int), void
1c880 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
1c890 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 REF: Set A Busy
1c8a0 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f Timeout.** METHO
1c8b0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a D: sqlite3.**.**
1c8c0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 ^This routine s
1c8d0 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 ets a [sqlite3_b
1c8e0 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 usy_handler | bu
1c8f0 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 sy handler] that
1c900 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 sleeps.** for a
1c910 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e specified amoun
1c920 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 t of time when a
1c930 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 table is locked
1c940 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a . ^The handler.
1c950 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 ** will sleep mu
1c960 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 ltiple times unt
1c970 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 il at least "ms"
1c980 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 milliseconds of
1c990 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 sleeping.** hav
1c9a0 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 e accumulated.
1c9b0 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 20 ^After at least
1c9c0 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 "ms" millisecond
1c9d0 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a s of sleeping,.*
1c9e0 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 * the handler re
1c9f0 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 turns 0 which ca
1ca00 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 uses [sqlite3_st
1ca10 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a ep()] to return.
1ca20 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d ** [SQLITE_BUSY]
1ca30 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 ..**.** ^Calling
1ca40 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 this routine wi
1ca50 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c th an argument l
1ca60 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 ess than or equa
1ca70 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 l to zero.** tur
1ca80 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 ns off all busy
1ca90 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 handlers..**.**
1caa0 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 ^(There can only
1cab0 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 be a single bus
1cac0 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 y handler for a
1cad0 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 particular.** [d
1cae0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1caf0 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69 76 65 6e on] at any given
1cb00 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f moment. If ano
1cb10 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 ther busy handle
1cb20 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64 r.** was defined
1cb30 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 (using [sqlite
1cb40 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 3_busy_handler()
1cb50 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c ]) prior to call
1cb60 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 ing.** this rout
1cb70 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 ine, that other
1cb80 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 busy handler is
1cb90 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a cleared.)^.**.**
1cba0 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41 See also: [PRA
1cbb0 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 GMA busy_timeout
1cbc0 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ].*/.SQLITE_API
1cbd0 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 int SQLITE_STDCA
1cbe0 4c 4c 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f LL sqlite3_busy_
1cbf0 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a timeout(sqlite3*
1cc00 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a , int ms);../*.*
1cc10 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 * CAPI3REF: Conv
1cc20 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 enience Routines
1cc30 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 For Running Que
1cc40 72 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 ries.** METHOD:
1cc50 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 sqlite3.**.** Th
1cc60 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 is is a legacy i
1cc70 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73 nterface that is
1cc80 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 preserved for b
1cc90 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 ackwards compati
1cca0 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f bility..** Use o
1ccb0 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 f this interface
1ccc0 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e is not recommen
1ccd0 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e ded..**.** Defin
1cce0 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 ition: A <b>resu
1ccf0 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 lt table</b> is
1cd00 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 memory data stru
1cd10 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79 cture created by
1cd20 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
1cd30 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e _get_table()] in
1cd40 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 terface. A resu
1cd50 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 lt table records
1cd60 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 the.** complete
1cd70 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 query results f
1cd80 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 rom one or more
1cd90 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 queries..**.** T
1cda0 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 he table concept
1cdb0 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 ually has a numb
1cdc0 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 er of rows and c
1cdd0 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 olumns. But.**
1cde0 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 these numbers ar
1cdf0 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 e not part of th
1ce00 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 e result table i
1ce10 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a tself. These.**
1ce20 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 numbers are obt
1ce30 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 ained separately
1ce40 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 . Let N be the
1ce50 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a number of rows.*
1ce60 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e * and M be the n
1ce70 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
1ce80 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 ..**.** A result
1ce90 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 table is an arr
1cea0 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 ay of pointers t
1ceb0 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 o zero-terminate
1cec0 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e d UTF-8 strings.
1ced0 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e .** There are (N
1cee0 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 +1)*M elements i
1cef0 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 n the array. Th
1cf00 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 e first M pointe
1cf10 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a rs point.** to z
1cf20 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 ero-terminated s
1cf30 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e trings that con
1cf40 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f tain the names o
1cf50 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a f the columns..*
1cf60 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 * The remaining
1cf70 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e entries all poin
1cf80 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c t to query resul
1cf90 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 ts. NULL values
1cfa0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 result.** in NU
1cfb0 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c LL pointers. Al
1cfc0 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 l other values a
1cfd0 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d re in their UTF-
1cfe0 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 8 zero-terminate
1cff0 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 d.** string repr
1d000 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 esentation as re
1d010 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
1d020 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
1d030 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c ]..**.** A resul
1d040 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f t table might co
1d050 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 nsist of one or
1d060 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f more memory allo
1d070 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 cations..** It i
1d080 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 s not safe to pa
1d090 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c ss a result tabl
1d0a0 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 e directly to [s
1d0b0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a qlite3_free()]..
1d0c0 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c ** A result tabl
1d0d0 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c e should be deal
1d0e0 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 located using [s
1d0f0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c qlite3_free_tabl
1d100 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 e()]..**.** ^(As
1d110 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 an example of t
1d120 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 he result table
1d130 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 format, suppose
1d140 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a a query result.*
1d150 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a * is as follows:
1d160 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
1d170 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 te><pre>.**
1d180 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c Name |
1d190 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d Age.** -
1d1a0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
1d1b0 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 ------.**
1d1c0 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 Alice | 4
1d1d0 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 3.** Bob
1d1e0 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 | 28.**
1d1f0 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 Cindy
1d200 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 | 21.** </pre
1d210 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ></blockquote>.*
1d220 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 *.** There are t
1d230 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 wo column (M==2)
1d240 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 and three rows
1d250 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 (N==3). Thus th
1d260 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c e.** result tabl
1d270 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e e has 8 entries.
1d280 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 Suppose the re
1d290 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 sult table is st
1d2a0 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 ored.** in an ar
1d2b0 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 ray names azResu
1d2c0 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 lt. Then azResu
1d2d0 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f lt holds this co
1d2e0 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c ntent:.**.** <bl
1d2f0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
1d300 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
1d310 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 t[0] = "Name
1d320 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
1d330 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 esult[1] = "
1d340 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 Age";.**
1d350 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 azResult[2]
1d360 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 = "Alice";.**
1d370 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
1d380 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 1;3] = "43";.**
1d390 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
1d3a0 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a #91;4] = "Bob";.
1d3b0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
1d3c0 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 lt[5] = "28"
1d3d0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 ;.** azRe
1d3e0 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 sult[6] = "C
1d3f0 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 indy";.**
1d400 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d azResult[7]
1d410 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 = "21";.** </pr
1d420 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 e></blockquote>)
1d430 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ^.**.** ^The sql
1d440 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
1d450 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 function evalua
1d460 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a tes one or more.
1d470 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 ** semicolon-sep
1d480 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 arated SQL state
1d490 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 ments in the zer
1d4a0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 o-terminated UTF
1d4b0 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 -8.** string of
1d4c0 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 its 2nd paramete
1d4d0 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 r and returns a
1d4e0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 result table to
1d4f0 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 the.** pointer g
1d500 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 iven in its 3rd
1d510 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a parameter..**.**
1d520 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 After the appli
1d530 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 cation has finis
1d540 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73 hed with the res
1d550 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 ult from sqlite3
1d560 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a _get_table(),.**
1d570 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 it must pass th
1d580 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 e result table p
1d590 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ointer to sqlite
1d5a0 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 3_free_table() i
1d5b0 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 n order to.** re
1d5c0 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 lease the memory
1d5d0 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 that was malloc
1d5e0 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 ed. Because of
1d5f0 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b the way the.** [
1d600 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
1d610 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e ] happens within
1d620 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 sqlite3_get_tab
1d630 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e le(), the callin
1d640 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 g.** function mu
1d650 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 st not try to ca
1d660 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ll [sqlite3_free
1d670 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f ()] directly. O
1d680 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f nly.** [sqlite3_
1d690 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 free_table()] is
1d6a0 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 able to release
1d6b0 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 the memory prop
1d6c0 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e erly and safely.
1d6d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
1d6e0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 e3_get_table() i
1d6f0 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c nterface is impl
1d700 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 emented as a wra
1d710 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b pper around.** [
1d720 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e sqlite3_exec()].
1d730 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 The sqlite3_ge
1d740 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e t_table() routin
1d750 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 e does not have
1d760 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 access.** to any
1d770 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 internal data s
1d780 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c tructures of SQL
1d790 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e ite. It uses on
1d7a0 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a ly the public.**
1d7b0 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e interface defin
1d7c0 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 ed here. As a c
1d7d0 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f onsequence, erro
1d7e0 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e rs that occur in
1d7f0 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 the.** wrapper
1d800 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 layer outside of
1d810 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 the internal [s
1d820 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 qlite3_exec()] c
1d830 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 all are not.** r
1d840 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 eflected in subs
1d850 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 equent calls to
1d860 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 [sqlite3_errcode
1d870 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 ()] or.** [sqlit
1d880 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f e3_errmsg()]..*/
1d890 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
1d8a0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
1d8b0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 qlite3_get_table
1d8c0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c (. sqlite3 *db,
1d8d0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 /* An
1d8e0 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f open database */
1d8f0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
1d900 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 Sql, /* SQL
1d910 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 to be evaluated
1d920 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a */. char ***paz
1d930 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 Result, /* Re
1d940 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 sults of the que
1d950 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 ry */. int *pnR
1d960 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a ow, /*
1d970 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c Number of resul
1d980 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 t rows written h
1d990 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e ere */. int *pn
1d9a0 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f Column, /
1d9b0 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 * Number of resu
1d9c0 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 lt columns writt
1d9d0 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 en here */. cha
1d9e0 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 r **pzErrmsg
1d9f0 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 /* Error msg
1da00 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a written here */.
1da10 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f );.SQLITE_API vo
1da20 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c id SQLITE_STDCAL
1da30 4c 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 L sqlite3_free_t
1da40 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 able(char **resu
1da50 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 lt);../*.** CAPI
1da60 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 3REF: Formatted
1da70 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 String Printing
1da80 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 Functions.**.**
1da90 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 These routines a
1daa0 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f re work-alikes o
1dab0 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 f the "printf()"
1dac0 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 family of funct
1dad0 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 ions.** from the
1dae0 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 standard C libr
1daf0 61 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f ary..** These ro
1db00 75 74 69 6e 65 73 20 75 6e 64 65 72 73 74 61 6e utines understan
1db10 64 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 63 6f d most of the co
1db20 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d 61 74 74 mmon K&R formatt
1db30 69 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a 20 ing options,.**
1db40 70 6c 75 73 20 73 6f 6d 65 20 61 64 64 69 74 69 plus some additi
1db50 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 onal non-standar
1db60 64 20 66 6f 72 6d 61 74 73 2c 20 64 65 74 61 69 d formats, detai
1db70 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f led below..** No
1db80 74 65 20 74 68 61 74 20 73 6f 6d 65 20 6f 66 20 te that some of
1db90 74 68 65 20 6d 6f 72 65 20 6f 62 73 63 75 72 65 the more obscure
1dba0 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 formatting opti
1dbb0 6f 6e 73 20 66 72 6f 6d 20 72 65 63 65 6e 74 0a ons from recent.
1dbc0 2a 2a 20 43 2d 6c 69 62 72 61 72 79 20 73 74 61 ** C-library sta
1dbd0 6e 64 61 72 64 73 20 61 72 65 20 6f 6d 69 74 74 ndards are omitt
1dbe0 65 64 20 66 72 6f 6d 20 74 68 69 73 20 69 6d 70 ed from this imp
1dbf0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 0a lementation..**.
1dc00 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
1dc10 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 mprintf() and sq
1dc20 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 lite3_vmprintf()
1dc30 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 routines write
1dc40 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 their.** results
1dc50 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 into memory obt
1dc60 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 ained from [sqli
1dc70 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a te3_malloc()]..*
1dc80 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 * The strings re
1dc90 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 turned by these
1dca0 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f two routines sho
1dcb0 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 uld be.** releas
1dcc0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 ed by [sqlite3_f
1dcd0 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 ree()]. ^Both r
1dce0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 outines return a
1dcf0 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 .** NULL pointer
1dd00 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c if [sqlite3_mal
1dd10 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 loc()] is unable
1dd20 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f to allocate eno
1dd30 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f ugh.** memory to
1dd40 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 hold the result
1dd50 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a ing string..**.*
1dd60 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f * ^(The sqlite3_
1dd70 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 snprintf() routi
1dd80 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f ne is similar to
1dd90 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 "snprintf()" fr
1dda0 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 om.** the standa
1ddb0 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 rd C library. T
1ddc0 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 he result is wri
1ddd0 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a tten into the.**
1dde0 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 buffer supplied
1ddf0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 as the second p
1de00 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 arameter whose s
1de10 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a ize is given by.
1de20 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72 ** the first par
1de30 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 ameter. Note tha
1de40 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 t the order of t
1de50 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 he.** first two
1de60 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 parameters is re
1de70 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 versed from snpr
1de80 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20 intf().)^ This
1de90 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 is an.** histori
1dea0 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 cal accident tha
1deb0 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 t cannot be fixe
1dec0 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 d without breaki
1ded0 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 ng.** backwards
1dee0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 compatibility.
1def0 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 ^(Note also that
1df00 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 sqlite3_snprint
1df10 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 f().** returns a
1df20 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 pointer to its
1df30 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f buffer instead o
1df40 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a f the number of.
1df50 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63 ** characters ac
1df60 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 tually written i
1df70 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29 nto the buffer.)
1df80 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 ^ We admit that
1df90 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f .** the number o
1dfa0 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69 f characters wri
1dfb0 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 tten would be a
1dfc0 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 more useful retu
1dfd0 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 rn.** value but
1dfe0 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 we cannot change
1dff0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 the implementat
1e000 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 ion of sqlite3_s
1e010 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 nprintf().** now
1e020 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e without breakin
1e030 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e g compatibility.
1e040 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 .**.** ^As long
1e050 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69 as the buffer si
1e060 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68 ze is greater th
1e070 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 an zero, sqlite3
1e080 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 _snprintf().** g
1e090 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 uarantees that t
1e0a0 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 he buffer is alw
1e0b0 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 ays zero-termina
1e0c0 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74 ted. ^The first
1e0d0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e .** parameter "n
1e0e0 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 " is the total s
1e0f0 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 ize of the buffe
1e100 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 r, including spa
1e110 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 ce for.** the ze
1e120 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 ro terminator.
1e130 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 So the longest s
1e140 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 tring that can b
1e150 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 e completely.**
1e160 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 written will be
1e170 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a n-1 characters..
1e180 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
1e190 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72 e3_vsnprintf() r
1e1a0 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61 outine is a vara
1e1b0 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 rgs version of s
1e1c0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
1e1d0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 )..**.** These r
1e1e0 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c outines all impl
1e1f0 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 ement some addit
1e200 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 ional formatting
1e210 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 .** options that
1e220 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 are useful for
1e230 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c constructing SQL
1e240 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 statements..**
1e250 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c All of the usual
1e260 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 printf() format
1e270 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 ting options app
1e280 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e ly. In addition
1e290 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 , there.** is ar
1e2a0 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 22 25 e "%q", "%Q", "%
1e2b0 77 22 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 w" and "%z" opti
1e2c0 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 ons..**.** ^(The
1e2d0 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 %q option works
1e2e0 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 like %s in that
1e2f0 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20 it substitutes
1e300 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 a nul-terminated
1e310 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 .** string from
1e320 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 the argument lis
1e330 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 t. But %q also
1e340 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c doubles every '\
1e350 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a '' character..**
1e360 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 %q is designed
1e370 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 for use inside a
1e380 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e string literal.
1e390 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 )^ By doubling
1e3a0 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 each '\''.** cha
1e3b0 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65 racter it escape
1e3c0 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72 s that character
1e3d0 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 and allows it t
1e3e0 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e o be inserted in
1e3f0 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 to.** the string
1e400 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d ..**.** For exam
1e410 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 ple, assume the
1e420 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 string variable
1e430 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 zText contains t
1e440 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a ext as follows:.
1e450 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
1e460 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 e><pre>.** char
1e470 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 *zText = "It's
1e480 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a a happy day!";.*
1e490 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 * </pre></blockq
1e4a0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 uote>.**.** One
1e4b0 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 can use this tex
1e4c0 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 t in an SQL stat
1e4d0 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 ement as follows
1e4e0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 :.**.** <blockqu
1e4f0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 ote><pre>.** ch
1e500 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 ar *zSQL = sqlit
1e510 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 e3_mprintf("INSE
1e520 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 RT INTO table VA
1e530 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 LUES('%q')", zTe
1e540 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 xt);.** sqlite3
1e550 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 _exec(db, zSQL,
1e560 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 0, 0, 0);.** sq
1e570 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 lite3_free(zSQL)
1e580 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f ;.** </pre></blo
1e590 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 ckquote>.**.** B
1e5a0 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f ecause the %q fo
1e5b0 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 rmat string is u
1e5c0 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 sed, the '\'' ch
1e5d0 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 aracter in zText
1e5e0 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 .** is escaped a
1e5f0 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 nd the SQL gener
1e600 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f ated is as follo
1e610 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b ws:.**.** <block
1e620 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 quote><pre>.**
1e630 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c INSERT INTO tabl
1e640 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 e1 VALUES('It''s
1e650 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a a happy day!').
1e660 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
1e670 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 quote>.**.** Thi
1e680 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 s is correct. H
1e690 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e ad we used %s in
1e6a0 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 stead of %q, the
1e6b0 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a generated SQL.*
1e6c0 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f * would have loo
1e6d0 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a ked like this:.*
1e6e0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
1e6f0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 ><pre>.** INSER
1e700 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 T INTO table1 VA
1e710 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70 LUES('It's a hap
1e720 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f py day!');.** </
1e730 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
1e740 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 >.**.** This sec
1e750 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 ond example is a
1e760 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 n SQL syntax err
1e770 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 or. As a genera
1e780 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c l rule you shoul
1e790 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 d.** always use
1e7a0 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 %q instead of %s
1e7b0 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 when inserting
1e7c0 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 text into a stri
1e7d0 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a ng literal..**.*
1e7e0 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f * ^(The %Q optio
1e7f0 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 n works like %q
1e800 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 except it also a
1e810 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 dds single quote
1e820 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 s around.** the
1e830 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 outside of the t
1e840 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 otal string. Ad
1e850 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 ditionally, if t
1e860 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 he parameter in
1e870 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 the.** argument
1e880 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 list is a NULL p
1e890 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 ointer, %Q subst
1e8a0 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20 itutes the text
1e8b0 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a "NULL" (without.
1e8c0 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 ** single quotes
1e8d0 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 ).)^ So, for ex
1e8e0 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 ample, one could
1e8f0 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f say:.**.** <blo
1e900 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a ckquote><pre>.**
1e910 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 char *zSQL = s
1e920 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 qlite3_mprintf("
1e930 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c INSERT INTO tabl
1e940 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a e VALUES(%Q)", z
1e950 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 Text);.** sqlit
1e960 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c e3_exec(db, zSQL
1e970 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 , 0, 0, 0);.**
1e980 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 sqlite3_free(zSQ
1e990 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 L);.** </pre></b
1e9a0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a lockquote>.**.**
1e9b0 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 The code above
1e9c0 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f will render a co
1e9d0 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d rrect SQL statem
1e9e0 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a ent in the zSQL.
1e9f0 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e ** variable even
1ea00 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 if the zText va
1ea10 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c riable is a NULL
1ea20 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 pointer..**.**
1ea30 5e 28 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61 ^(The "%w" forma
1ea40 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 tting option is
1ea50 6c 69 6b 65 20 22 25 71 22 20 65 78 63 65 70 74 like "%q" except
1ea60 20 74 68 61 74 20 69 74 20 65 78 70 65 63 74 73 that it expects
1ea70 20 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74 61 69 to.** be contai
1ea80 6e 65 64 20 77 69 74 68 69 6e 20 64 6f 75 62 6c ned within doubl
1ea90 65 2d 71 75 6f 74 65 73 20 69 6e 73 74 65 61 64 e-quotes instead
1eaa0 20 6f 66 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 of single quote
1eab0 73 2c 20 61 6e 64 20 69 74 0a 2a 2a 20 65 73 63 s, and it.** esc
1eac0 61 70 65 73 20 74 68 65 20 64 6f 75 62 6c 65 2d apes the double-
1ead0 71 75 6f 74 65 20 63 68 61 72 61 63 74 65 72 20 quote character
1eae0 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 73 instead of the s
1eaf0 69 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20 63 ingle-quote.** c
1eb00 68 61 72 61 63 74 65 72 2e 29 5e 20 20 54 68 65 haracter.)^ The
1eb10 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 "%w" formatting
1eb20 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 74 65 6e option is inten
1eb30 64 65 64 20 66 6f 72 20 73 61 66 65 6c 79 20 69 ded for safely i
1eb40 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 61 62 6c nserting.** tabl
1eb50 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d e and column nam
1eb60 65 73 20 69 6e 74 6f 20 61 20 63 6f 6e 73 74 72 es into a constr
1eb70 75 63 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d ucted SQL statem
1eb80 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 ent..**.** ^(The
1eb90 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 "%z" formatting
1eba0 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 option works li
1ebb0 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74 68 ke "%s" but with
1ebc0 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e the.** addition
1ebd0 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20 that after the
1ebe0 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 string has been
1ebf0 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 read and copied
1ec00 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 into.** the resu
1ec10 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 lt, [sqlite3_fre
1ec20 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f e()] is called o
1ec30 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 n the input stri
1ec40 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f ng.)^.*/.SQLITE_
1ec50 41 50 49 20 63 68 61 72 20 2a 53 51 4c 49 54 45 API char *SQLITE
1ec60 5f 43 44 45 43 4c 20 73 71 6c 69 74 65 33 5f 6d _CDECL sqlite3_m
1ec70 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 printf(const cha
1ec80 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f r*,...);.SQLITE_
1ec90 41 50 49 20 63 68 61 72 20 2a 53 51 4c 49 54 45 API char *SQLITE
1eca0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
1ecb0 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 _vmprintf(const
1ecc0 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b char*, va_list);
1ecd0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 .SQLITE_API char
1ece0 20 2a 53 51 4c 49 54 45 5f 43 44 45 43 4c 20 73 *SQLITE_CDECL s
1ecf0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
1ed00 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 int,char*,const
1ed10 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c char*, ...);.SQL
1ed20 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 53 51 ITE_API char *SQ
1ed30 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
1ed40 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 ite3_vsnprintf(i
1ed50 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 nt,char*,const c
1ed60 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a har*, va_list);.
1ed70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1ed80 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 Memory Allocati
1ed90 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a on Subsystem.**.
1eda0 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f ** The SQLite co
1edb0 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68 re uses these th
1edc0 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 ree routines for
1edd0 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a all of its own.
1ede0 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f ** internal memo
1edf0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 ry allocation ne
1ee00 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 eds. "Core" in t
1ee10 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 he previous sent
1ee20 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 ence.** does not
1ee30 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 include operati
1ee40 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 ng-system specif
1ee50 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 ic VFS implement
1ee60 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 ation. The.** W
1ee70 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 indows VFS uses
1ee80 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 native malloc()
1ee90 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 and free() for s
1eea0 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a ome operations..
1eeb0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
1eec0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 e3_malloc() rout
1eed0 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f ine returns a po
1eee0 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b inter to a block
1eef0 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 .** of memory at
1ef00 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 least N bytes i
1ef10 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 n length, where
1ef20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 N is the paramet
1ef30 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 er..** ^If sqlit
1ef40 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 e3_malloc() is u
1ef50 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 nable to obtain
1ef60 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a sufficient free.
1ef70 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 ** memory, it re
1ef80 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 turns a NULL poi
1ef90 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 nter. ^If the p
1efa0 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a arameter N to.**
1efb0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
1efc0 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 ) is zero or neg
1efd0 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 ative then sqlit
1efe0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 e3_malloc() retu
1eff0 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f rns.** a NULL po
1f000 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 inter..**.** ^Th
1f010 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 e sqlite3_malloc
1f020 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f 64(N) routine wo
1f030 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a rks just like.**
1f040 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
1f050 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e N) except that N
1f060 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 is an unsigned
1f070 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69 64-bit integer i
1f080 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73 nstead.** of a s
1f090 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74 igned 32-bit int
1f0a0 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c eger..**.** ^Cal
1f0b0 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 ling sqlite3_fre
1f0c0 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 e() with a point
1f0d0 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 er previously re
1f0e0 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c turned.** by sql
1f0f0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 ite3_malloc() or
1f100 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
1f110 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 () releases that
1f120 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 memory so.** th
1f130 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 at it might be r
1f140 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c eused. ^The sql
1f150 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 ite3_free() rout
1f160 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f ine is.** a no-o
1f170 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 p if is called w
1f180 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 ith a NULL point
1f190 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e er. Passing a N
1f1a0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 ULL pointer.** t
1f1b0 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 o sqlite3_free()
1f1c0 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 is harmless. A
1f1d0 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 fter being freed
1f1e0 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 , memory.** shou
1f1f0 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 ld neither be re
1f200 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 ad nor written.
1f210 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 Even reading pr
1f220 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a eviously freed.*
1f230 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 * memory might r
1f240 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 esult in a segme
1f250 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 ntation fault or
1f260 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 other severe er
1f270 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 ror..** Memory c
1f280 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 orruption, a seg
1f290 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c mentation fault,
1f2a0 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 or other severe
1f2b0 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 error.** might
1f2c0 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 result if sqlite
1f2d0 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 3_free() is call
1f2e0 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 ed with a non-NU
1f2f0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a LL pointer that.
1f300 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 ** was not obtai
1f310 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 ned from sqlite3
1f320 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c _malloc() or sql
1f330 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a ite3_realloc()..
1f340 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
1f350 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 e3_realloc(X,N)
1f360 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 interface attemp
1f370 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a ts to resize a.*
1f380 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 * prior memory a
1f390 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62 llocation X to b
1f3a0 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 e at least N byt
1f3b0 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58 es..** ^If the X
1f3c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
1f3d0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c lite3_realloc(X,
1f3e0 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 N).** is a NULL
1f3f0 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 pointer then its
1f400 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 behavior is ide
1f410 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e ntical to callin
1f420 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c g.** sqlite3_mal
1f430 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 loc(N)..** ^If t
1f440 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 he N parameter t
1f450 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f o sqlite3_reallo
1f460 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f c(X,N) is zero o
1f470 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 r.** negative th
1f480 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 en the behavior
1f490 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 is exactly the s
1f4a0 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a ame as calling.*
1f4b0 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58 * sqlite3_free(X
1f4c0 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 )..** ^sqlite3_r
1f4d0 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 ealloc(X,N) retu
1f4e0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
1f4f0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 a memory alloca
1f500 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 tion.** of at le
1f510 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 ast N bytes in s
1f520 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 ize or NULL if i
1f530 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f nsufficient memo
1f540 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e ry is available.
1f550 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 .** ^If M is the
1f560 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 size of the pri
1f570 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 or allocation, t
1f580 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 hen min(N,M) byt
1f590 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 es.** of the pri
1f5a0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 or allocation ar
1f5b0 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 e copied into th
1f5c0 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 e beginning of b
1f5d0 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a uffer returned.*
1f5e0 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 * by sqlite3_rea
1f5f0 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68 lloc(X,N) and th
1f600 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 e prior allocati
1f610 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 on is freed..**
1f620 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c ^If sqlite3_real
1f630 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 loc(X,N) returns
1f640 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70 NULL and N is p
1f650 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68 ositive, then th
1f660 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63 e.** prior alloc
1f670 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65 ation is not fre
1f680 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ed..**.** ^The s
1f690 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 qlite3_realloc64
1f6a0 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73 (X,N) interfaces
1f6b0 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20 works the same
1f6c0 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 as.** sqlite3_re
1f6d0 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70 alloc(X,N) excep
1f6e0 74 20 74 68 61 74 20 4e 20 69 73 20 61 20 36 34 t that N is a 64
1f6f0 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e -bit unsigned in
1f700 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a teger instead.**
1f710 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 67 of a 32-bit sig
1f720 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a ned integer..**.
1f730 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65 ** ^If X is a me
1f740 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
1f750 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 previously obtai
1f760 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 ned from sqlite3
1f770 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 _malloc(),.** sq
1f780 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 lite3_malloc64()
1f790 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f , sqlite3_reallo
1f7a0 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f c(), or sqlite3_
1f7b0 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65 realloc64(), the
1f7c0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 n.** sqlite3_msi
1f7d0 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 74 68 ze(X) returns th
1f7e0 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d e size of that m
1f7f0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
1f800 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 in bytes..** ^T
1f810 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
1f820 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69 d by sqlite3_msi
1f830 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c ze(X) might be l
1f840 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e arger than the n
1f850 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 umber.** of byte
1f860 73 20 72 65 71 75 65 73 74 65 64 20 77 68 65 6e s requested when
1f870 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64 X was allocated
1f880 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55 . ^If X is a NU
1f890 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a LL pointer then.
1f8a0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 ** sqlite3_msize
1f8b0 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f (X) returns zero
1f8c0 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74 . If X points t
1f8d0 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74 o something that
1f8e0 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 is not.** the b
1f8f0 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f eginning of memo
1f900 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f ry allocation, o
1f910 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74 r if it points t
1f920 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 o a formerly.**
1f930 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c valid memory all
1f940 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73 ocation that has
1f950 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c now been freed,
1f960 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 then the behavi
1f970 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 or.** of sqlite3
1f980 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64 _msize(X) is und
1f990 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69 efined and possi
1f9a0 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a bly harmful..**.
1f9b0 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 ** ^The memory r
1f9c0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 eturned by sqlit
1f9d0 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c e3_malloc(), sql
1f9e0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a ite3_realloc(),.
1f9f0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f ** sqlite3_mallo
1fa00 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 c64(), and sqlit
1fa10 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a e3_realloc64().*
1fa20 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 * is always alig
1fa30 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 ned to at least
1fa40 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 an 8 byte bounda
1fa50 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 ry, or to a.** 4
1fa60 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 byte boundary i
1fa70 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f f the [SQLITE_4_
1fa80 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c BYTE_ALIGNED_MAL
1fa90 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d LOC] compile-tim
1faa0 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 e.** option is u
1fab0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 sed..**.** In SQ
1fac0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 Lite version 3.5
1fad0 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 .0 and 3.5.1, it
1fae0 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f was possible to
1faf0 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 define.** the S
1fb00 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 QLITE_OMIT_MEMOR
1fb10 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 Y_ALLOCATION whi
1fb20 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 ch would cause t
1fb30 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 he built-in.** i
1fb40 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
1fb50 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
1fb60 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 to be omitted.
1fb70 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a That capability.
1fb80 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 ** is no longer
1fb90 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 provided. Only
1fba0 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 built-in memory
1fbb0 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 allocators can b
1fbc0 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 e used..**.** Pr
1fbd0 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 ior to SQLite ve
1fbe0 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 rsion 3.7.10, th
1fbf0 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 e Windows OS int
1fc00 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c erface layer cal
1fc10 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 led.** the syste
1fc20 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 m malloc() and f
1fc30 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 ree() directly w
1fc40 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a hen converting.*
1fc50 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 * filenames betw
1fc60 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e een the UTF-8 en
1fc70 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 coding used by S
1fc80 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 QLite.** and wha
1fc90 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 tever filename e
1fca0 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 ncoding is used
1fcb0 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 by the particula
1fcc0 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 r Windows.** ins
1fcd0 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f tallation. Memo
1fce0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 ry allocation er
1fcf0 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 74 rors were detect
1fd00 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 ed, but.** they
1fd10 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 were reported ba
1fd20 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 ck as [SQLITE_CA
1fd30 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 NTOPEN] or.** [S
1fd40 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 QLITE_IOERR] rat
1fd50 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 her than [SQLITE
1fd60 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 _NOMEM]..**.** T
1fd70 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d he pointer argum
1fd80 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 ents to [sqlite3
1fd90 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 _free()] and [sq
1fda0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d lite3_realloc()]
1fdb0 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 .** must be eith
1fdc0 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 er NULL or else
1fdd0 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 pointers obtaine
1fde0 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a d from a prior.*
1fdf0 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 * invocation of
1fe00 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
1fe10 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 )] or [sqlite3_r
1fe20 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 ealloc()] that h
1fe30 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 ave.** not yet b
1fe40 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a een released..**
1fe50 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
1fe60 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 ion must not rea
1fe70 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 d or write any p
1fe80 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 art of.** a bloc
1fe90 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 k of memory afte
1fea0 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 r it has been re
1feb0 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 leased using.**
1fec0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
1fed0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 or [sqlite3_rea
1fee0 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 lloc()]..*/.SQLI
1fef0 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c TE_API void *SQL
1ff00 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
1ff10 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b te3_malloc(int);
1ff20 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
1ff30 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c *SQLITE_STDCALL
1ff40 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 sqlite3_malloc6
1ff50 34 28 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 4(sqlite3_uint64
1ff60 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f );.SQLITE_API vo
1ff70 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 id *SQLITE_STDCA
1ff80 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c LL sqlite3_reall
1ff90 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a oc(void*, int);.
1ffa0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
1ffb0 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 *SQLITE_STDCALL
1ffc0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 sqlite3_realloc6
1ffd0 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 4(void*, sqlite3
1ffe0 5f 75 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 _uint64);.SQLITE
1fff0 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45 _API void SQLITE
20000 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
20010 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 53 51 _free(void*);.SQ
20020 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 LITE_API sqlite3
20030 5f 75 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 _uint64 SQLITE_S
20040 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d TDCALL sqlite3_m
20050 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a size(void*);../*
20060 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 .** CAPI3REF: Me
20070 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 mory Allocator S
20080 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 tatistics.**.**
20090 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 SQLite provides
200a0 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 these two interf
200b0 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 aces for reporti
200c0 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 ng on the status
200d0 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 .** of the [sqli
200e0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b te3_malloc()], [
200f0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c sqlite3_free()],
20100 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 and [sqlite3_re
20110 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 alloc()].** rout
20120 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d ines, which form
20130 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 the built-in me
20140 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
20150 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a subsystem..**.**
20160 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d ^The [sqlite3_m
20170 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f emory_used()] ro
20180 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 utine returns th
20190 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
201a0 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 s.** of memory c
201b0 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e urrently outstan
201c0 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 ding (malloced b
201d0 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a ut not freed)..*
201e0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f * ^The [sqlite3_
201f0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 memory_highwater
20200 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 ()] routine retu
20210 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a rns the maximum.
20220 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c ** value of [sql
20230 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 ite3_memory_used
20240 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 ()] since the hi
20250 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a gh-water mark.**
20260 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e was last reset.
20270 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 ^The values re
20280 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
20290 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 e3_memory_used()
202a0 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 ] and.** [sqlite
202b0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 3_memory_highwat
202c0 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e er()] include an
202d0 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 y overhead.** ad
202e0 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e ded by SQLite in
202f0 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 its implementat
20300 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f ion of [sqlite3_
20310 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 malloc()],.** bu
20320 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 t not overhead a
20330 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 dded by the any
20340 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 underlying syste
20350 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 m library.** rou
20360 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 tines that [sqli
20370 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 te3_malloc()] ma
20380 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 y call..**.** ^T
20390 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 he memory high-w
203a0 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 ater mark is res
203b0 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e et to the curren
203c0 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 t value of.** [s
203d0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 qlite3_memory_us
203e0 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c ed()] if and onl
203f0 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 y if the paramet
20400 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 er to.** [sqlite
20410 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 3_memory_highwat
20420 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 er()] is true.
20430 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 ^The value retur
20440 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 ned.** by [sqlit
20450 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 e3_memory_highwa
20460 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 ter(1)] is the h
20470 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a igh-water mark.*
20480 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 * prior to the r
20490 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f eset..*/.SQLITE_
204a0 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 API sqlite3_int6
204b0 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 4 SQLITE_STDCALL
204c0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f sqlite3_memory_
204d0 75 73 65 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 used(void);.SQLI
204e0 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 TE_API sqlite3_i
204f0 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43 nt64 SQLITE_STDC
20500 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f ALL sqlite3_memo
20510 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 ry_highwater(int
20520 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a resetFlag);../*
20530 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 .** CAPI3REF: Ps
20540 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 eudo-Random Numb
20550 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a er Generator.**.
20560 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 ** SQLite contai
20570 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 ns a high-qualit
20580 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 y pseudo-random
20590 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 number generator
205a0 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a (PRNG) used to.
205b0 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d ** select random
205c0 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 [ROWID | ROWIDs
205d0 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 ] when inserting
205e0 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 new records int
205f0 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a o a table that.*
20600 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 * already uses t
20610 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 he largest possi
20620 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 ble [ROWID]. Th
20630 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 e PRNG is also u
20640 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 sed for.** the b
20650 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 uild-in random()
20660 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 and randomblob(
20670 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e ) SQL functions.
20680 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 This interface
20690 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 allows.** appli
206a0 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 cations to acces
206b0 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 s the same PRNG
206c0 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 for other purpos
206d0 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c es..**.** ^A cal
206e0 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e l to this routin
206f0 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 e stores N bytes
20700 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 of randomness i
20710 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a nto buffer P..**
20720 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74 65 ^The P paramete
20730 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 r can be a NULL
20740 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e pointer..**.** ^
20750 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 If this routine
20760 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 has not been pre
20770 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f viously called o
20780 72 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 r if the previou
20790 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 s.** call had N
207a0 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 less than one or
207b0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
207c0 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20 for P, then the
207d0 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 PRNG is.** seede
207e0 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 d using randomne
207f0 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d ss obtained from
20800 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 the xRandomness
20810 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 method of.** th
20820 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 e default [sqlit
20830 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a e3_vfs] object..
20840 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76 69 ** ^If the previ
20850 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 ous call to this
20860 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20 routine had an
20870 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 N of 1 or more a
20880 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c nd a.** non-NULL
20890 20 50 20 74 68 65 6e 20 74 68 65 20 70 73 65 75 P then the pseu
208a0 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 do-randomness is
208b0 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e generated.** in
208c0 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 ternally and wit
208d0 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f hout recourse to
208e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 the [sqlite3_vf
208f0 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a s] xRandomness.*
20900 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c * method..*/.SQL
20910 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c ITE_API void SQL
20920 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
20930 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 te3_randomness(i
20940 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a nt N, void *P);.
20950 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
20960 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 Compile-Time Au
20970 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c thorization Call
20980 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a backs.** METHOD:
20990 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e sqlite3.**.** ^
209a0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 This routine reg
209b0 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72 isters an author
209c0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 izer callback wi
209d0 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a th a particular.
209e0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
209f0 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 nection], suppli
20a00 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 ed in the first
20a10 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 argument..** ^Th
20a20 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
20a30 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 lback is invoked
20a40 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e as SQL statemen
20a50 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d ts are being com
20a60 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c piled.** by [sql
20a70 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 ite3_prepare()]
20a80 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 or its variants
20a90 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
20aa0 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 _v2()],.** [sqli
20ab0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d te3_prepare16()]
20ac0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 and [sqlite3_pr
20ad0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 epare16_v2()].
20ae0 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 ^At various.** p
20af0 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 oints during the
20b00 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f compilation pro
20b10 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 cess, as logic i
20b20 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a s being created.
20b30 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 ** to perform va
20b40 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 rious actions, t
20b50 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
20b60 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
20b70 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 d to.** see if t
20b80 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 hose actions are
20b90 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 allowed. ^The
20ba0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
20bb0 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 ack should.** re
20bc0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d turn [SQLITE_OK]
20bd0 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 to allow the ac
20be0 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 tion, [SQLITE_IG
20bf0 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f NORE] to disallo
20c00 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 w the.** specifi
20c10 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c c action but all
20c20 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 ow the SQL state
20c30 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 ment to continue
20c40 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c to be.** compil
20c50 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 ed, or [SQLITE_D
20c60 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 ENY] to cause th
20c70 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 e entire SQL sta
20c80 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 tement to be.**
20c90 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e rejected with an
20ca0 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 error. ^If the
20cb0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
20cc0 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 back returns.**
20cd0 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 any value other
20ce0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e than [SQLITE_IGN
20cf0 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b ORE], [SQLITE_OK
20d00 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 ], or [SQLITE_DE
20d10 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 NY].** then the
20d20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
20d30 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 _v2()] or equiva
20d40 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 lent call that t
20d50 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 riggered.** the
20d60 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 authorizer will
20d70 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 fail with an err
20d80 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a or message..**.*
20d90 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 * When the callb
20da0 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c ack returns [SQL
20db0 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 ITE_OK], that me
20dc0 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f ans the operatio
20dd0 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 n.** requested i
20de0 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 s ok. ^When the
20df0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
20e00 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c s [SQLITE_DENY],
20e10 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
20e20 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f _prepare_v2()] o
20e30 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c r equivalent cal
20e40 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 l that triggered
20e50 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a the.** authoriz
20e60 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 er will fail wit
20e70 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 h an error messa
20e80 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 ge explaining th
20e90 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 at.** access is
20ea0 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e denied. .**.** ^
20eb0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 The first parame
20ec0 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f ter to the autho
20ed0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 rizer callback i
20ee0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 s a copy of the
20ef0 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 third.** paramet
20f00 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 er to the sqlite
20f10 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 3_set_authorizer
20f20 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 () interface. ^T
20f30 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
20f40 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 ter.** to the ca
20f50 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 llback is an int
20f60 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 eger [SQLITE_COP
20f70 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d Y | action code]
20f80 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a that specifies.
20f90 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 ** the particula
20fa0 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 r action to be a
20fb0 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 uthorized. ^The
20fc0 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 third through si
20fd0 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a xth parameters.*
20fe0 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 * to the callbac
20ff0 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 k are zero-termi
21000 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 nated strings th
21010 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 at contain addit
21020 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 ional.** details
21030 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f about the actio
21040 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a n to be authoriz
21050 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 ed..**.** ^If th
21060 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 e action code is
21070 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a [SQLITE_READ].*
21080 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 * and the callba
21090 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 ck returns [SQLI
210a0 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 TE_IGNORE] then
210b0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 the.** [prepared
210c0 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 statement] stat
210d0 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 ement is constru
210e0 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 cted to substitu
210f0 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c te.** a NULL val
21100 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 ue in place of t
21110 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 he table column
21120 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a that would have.
21130 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 ** been read if
21140 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 [SQLITE_OK] had
21150 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 been returned.
21160 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f The [SQLITE_IGNO
21170 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 RE].** return ca
21180 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e n be used to den
21190 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 y an untrusted u
211a0 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e ser access to in
211b0 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 dividual.** colu
211c0 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a mns of a table..
211d0 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f ** ^If the actio
211e0 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 n code is [SQLIT
211f0 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 E_DELETE] and th
21200 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 e callback retur
21210 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 ns.** [SQLITE_IG
21220 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b NORE] then the [
21230 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f DELETE] operatio
21240 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 n proceeds but t
21250 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 he.** [truncate
21260 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 optimization] is
21270 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c disabled and al
21280 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 l rows are delet
21290 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e ed individually.
212a0 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 .**.** An author
212b0 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65 izer is used whe
212c0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 n [sqlite3_prepa
212d0 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a re | preparing].
212e0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ** SQL statement
212f0 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 s from an untrus
21300 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 ted source, to e
21310 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53 nsure that the S
21320 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a QL statements.**
21330 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 do not try to a
21340 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20 ccess data they
21350 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 are not allowed
21360 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 to see, or that
21370 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 they do not.** t
21380 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 ry to execute ma
21390 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e licious statemen
213a0 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 ts that damage t
213b0 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f he database. Fo
213c0 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e r.** example, an
213d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 application may
213e0 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f allow a user to
213f0 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 enter arbitrary
21400 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 .** SQL queries
21410 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 for evaluation b
21420 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 y a database. B
21430 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 ut the applicati
21440 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 on does.** not w
21450 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 ant the user to
21460 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 be able to make
21470 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 arbitrary change
21480 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 s to the.** data
21490 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 base. An author
214a0 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 izer could then
214b0 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 be put in place
214c0 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 while the.** use
214d0 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 r-entered SQL is
214e0 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f being [sqlite3_
214f0 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 prepare | prepar
21500 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 ed] that.** disa
21510 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 llows everything
21520 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d except [SELECT]
21530 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a statements..**.
21540 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 ** Applications
21550 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f that need to pro
21560 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e cess SQL from un
21570 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a trusted sources.
21580 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f ** might also co
21590 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 nsider lowering
215a0 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 resource limits
215b0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c using [sqlite3_l
215c0 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c imit()].** and l
215d0 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 imiting database
215e0 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 size using the
215f0 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d [max_page_count]
21600 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 [PRAGMA].** in
21610 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e addition to usin
21620 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e g an authorizer.
21630 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 .**.** ^(Only a
21640 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 single authorize
21650 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 r can be in plac
21660 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 e on a database
21670 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 connection.** at
21680 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 a time. Each c
21690 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 all to sqlite3_s
216a0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 et_authorizer ov
216b0 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 errides the.** p
216c0 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 revious call.)^
216d0 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 ^Disable the au
216e0 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 thorizer by inst
216f0 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 alling a NULL ca
21700 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 llback..** The a
21710 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 uthorizer is dis
21720 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 abled by default
21730 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 ..**.** The auth
21740 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
21750 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 must not do anyt
21760 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d hing that will m
21770 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 odify.** the dat
21780 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
21790 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 that invoked th
217a0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
217b0 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 lback..** Note t
217c0 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 hat [sqlite3_pre
217d0 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b pare_v2()] and [
217e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
217f0 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 both modify thei
21800 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f r.** database co
21810 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 nnections for th
21820 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f e meaning of "mo
21830 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 dify" in this pa
21840 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e ragraph..**.** ^
21850 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 When [sqlite3_pr
21860 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 epare_v2()] is u
21870 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 sed to prepare a
21880 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a statement, the.
21890 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 ** statement mig
218a0 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 ht be re-prepare
218b0 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 d during [sqlite
218c0 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 3_step()] due to
218d0 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 a .** schema ch
218e0 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 ange. Hence, th
218f0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 e application sh
21900 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 ould ensure that
21910 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 the.** correct
21920 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
21930 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 ack remains in p
21940 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 lace during the
21950 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
21960 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 ..**.** ^Note th
21970 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 at the authorize
21980 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e r callback is in
21990 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e voked only durin
219a0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 g.** [sqlite3_pr
219b0 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 epare()] or its
219c0 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f variants. Autho
219d0 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a rization is not.
219e0 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 ** performed dur
219f0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 ing statement ev
21a00 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c aluation in [sql
21a10 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e ite3_step()], un
21a20 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 less.** as state
21a30 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 d in the previou
21a40 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c s paragraph, sql
21a50 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f ite3_step() invo
21a60 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 kes.** sqlite3_p
21a70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 repare_v2() to r
21a80 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 eprepare a state
21a90 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 ment after a sch
21aa0 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53 ema change..*/.S
21ab0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 QLITE_API int SQ
21ac0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
21ad0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 ite3_set_authori
21ae0 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c zer(. sqlite3*,
21af0 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 . int (*xAuth)(
21b00 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 void*,int,const
21b10 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 char*,const char
21b20 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f *,const char*,co
21b30 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f nst char*),. vo
21b40 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b id *pUserData.);
21b50 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
21b60 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 : Authorizer Ret
21b70 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 urn Codes.**.**
21b80 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 The [sqlite3_set
21b90 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 _authorizer | au
21ba0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
21bb0 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 k function] must
21bc0 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 .** return eithe
21bd0 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 r [SQLITE_OK] or
21be0 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 one of these tw
21bf0 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f o constants in o
21c00 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 rder.** to signa
21c10 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 l SQLite whether
21c20 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 or not the acti
21c30 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e on is permitted.
21c40 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 See the.** [sq
21c50 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 lite3_set_author
21c60 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 izer | authorize
21c70 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d r documentation]
21c80 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a for additional.
21c90 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a ** information..
21ca0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 **.** Note that
21cb0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 SQLITE_IGNORE is
21cc0 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20 also used as a
21cd0 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75 [conflict resolu
21ce0 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65 tion mode].** re
21cf0 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 turned from the
21d00 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e [sqlite3_vtab_on
21d10 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 _conflict()] int
21d20 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 erface..*/.#defi
21d30 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 ne SQLITE_DENY
21d40 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 1 /* Abort th
21d50 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
21d60 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f with an error */
21d70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
21d80 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f IGNORE 2 /* Do
21d90 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 n't allow access
21da0 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 , but don't gene
21db0 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f rate an error */
21dc0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
21dd0 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 : Authorizer Act
21de0 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 ion Codes.**.**
21df0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 The [sqlite3_set
21e00 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 _authorizer()] i
21e10 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 nterface registe
21e20 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 rs a callback fu
21e30 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 nction.** that i
21e40 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 s invoked to aut
21e50 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53 horize certain S
21e60 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 QL statement act
21e70 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 ions. The.** se
21e80 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 cond parameter t
21e90 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 o the callback i
21ea0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 s an integer cod
21eb0 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 e that specifies
21ec0 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 .** what action
21ed0 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 is being authori
21ee0 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 zed. These are
21ef0 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 the integer acti
21f00 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a on codes that.**
21f10 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
21f20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 callback may be
21f30 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 passed..**.** Th
21f40 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 ese action code
21f50 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 values signify w
21f60 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 hat kind of oper
21f70 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a ation is to be.*
21f80 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 * authorized. T
21f90 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 he 3rd and 4th p
21fa0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 arameters to the
21fb0 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a authorization.*
21fc0 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 * callback funct
21fd0 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 ion will be para
21fe0 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 meters or NULL d
21ff0 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 epending on whic
22000 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f h of these.** co
22010 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74 des is used as t
22020 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
22030 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20 ter. ^(The 5th
22040 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
22050 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 .** authorizer c
22060 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e allback is the n
22070 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 ame of the datab
22080 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 ase ("main", "te
22090 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 mp",.** etc.) if
220a0 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 applicable.)^
220b0 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 ^The 6th paramet
220c0 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 er to the author
220d0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a izer callback.**
220e0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 is the name of
220f0 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 the inner-most t
22100 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 rigger or view t
22110 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 hat is responsib
22120 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 le for.** the ac
22130 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 cess attempt or
22140 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 NULL if this acc
22150 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 ess attempt is d
22160 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 irectly from.**
22170 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f top-level SQL co
22180 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a de..*/./********
22190 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
221a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
221b0 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a *** 3rd ********
221c0 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a **** 4th *******
221d0 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ****/.#define SQ
221e0 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 LITE_CREATE_INDE
221f0 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f X 1 /
22200 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 * Index Name
22210 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 Table Name
22220 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
22230 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 ITE_CREATE_TABLE
22240 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 2 /*
22250 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
22260 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
22270 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
22280 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 TE_CREATE_TEMP_I
22290 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 NDEX 3 /*
222a0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 Index Name
222b0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
222c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
222d0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 E_CREATE_TEMP_TA
222e0 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 BLE 4 /* T
222f0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e able Name N
22300 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
22310 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
22320 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 _CREATE_TEMP_TRI
22330 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 GGER 5 /* Tr
22340 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 igger Name Ta
22350 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f ble Name */
22360 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
22370 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 CREATE_TEMP_VIEW
22380 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 6 /* Vie
22390 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c w Name NUL
223a0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
223b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
223c0 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 REATE_TRIGGER
223d0 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 7 /* Trig
223e0 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c ger Name Tabl
223f0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
22400 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 define SQLITE_CR
22410 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 EATE_VIEW
22420 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 8 /* View
22430 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
22440 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
22450 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c efine SQLITE_DEL
22460 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 ETE
22470 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 9 /* Table
22480 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 Name NULL
22490 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
224a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
224b0 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 _INDEX
224c0 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 10 /* Index N
224d0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e ame Table N
224e0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
224f0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
22500 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 TABLE
22510 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 11 /* Table Na
22520 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
22530 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
22540 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 ne SQLITE_DROP_T
22550 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 EMP_INDEX 1
22560 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 2 /* Index Nam
22570 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d e Table Nam
22580 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
22590 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 e SQLITE_DROP_TE
225a0 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 MP_TABLE 13
225b0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
225c0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
225d0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
225e0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d SQLITE_DROP_TEM
225f0 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20 P_TRIGGER 14
22600 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d /* Trigger Nam
22610 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 e Table Name
22620 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
22630 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 SQLITE_DROP_TEMP
22640 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20 _VIEW 15
22650 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 /* View Name
22660 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
22670 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
22680 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 QLITE_DROP_TRIGG
22690 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20 ER 16
226a0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 /* Trigger Name
226b0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
226c0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
226d0 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 LITE_DROP_VIEW
226e0 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 17 /
226f0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 * View Name
22700 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
22710 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
22720 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 ITE_INSERT
22730 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 18 /*
22740 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
22750 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
22760 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
22770 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 TE_PRAGMA
22780 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 19 /*
22790 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 Pragma Name
227a0 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 1st arg or NULL
227b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
227c0 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 E_READ
227d0 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 20 /* T
227e0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 able Name C
227f0 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a olumn Name *
22800 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
22810 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 _SELECT
22820 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 21 /* NU
22830 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 LL NU
22840 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
22850 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
22860 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 TRANSACTION
22870 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 22 /* Ope
22880 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c ration NUL
22890 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
228a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 #define SQLITE_U
228b0 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20 PDATE
228c0 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 23 /* Tabl
228d0 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 e Name Colu
228e0 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 mn Name */.#
228f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 define SQLITE_AT
22900 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 TACH
22910 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 24 /* Filen
22920 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 ame NULL
22930 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
22940 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 efine SQLITE_DET
22950 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 ACH
22960 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 25 /* Databa
22970 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 se Name NULL
22980 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
22990 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 fine SQLITE_ALTE
229a0 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 R_TABLE
229b0 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 26 /* Databas
229c0 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e e Name Table N
229d0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
229e0 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 ine SQLITE_REIND
229f0 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20 EX
22a00 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 27 /* Index Na
22a10 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
22a20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
22a30 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a ne SQLITE_ANALYZ
22a40 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 E 2
22a50 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 8 /* Table Nam
22a60 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
22a70 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
22a80 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
22a90 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 VTABLE 29
22aa0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
22ab0 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d Module Nam
22ac0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 e */.#define
22ad0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 SQLITE_DROP_VTA
22ae0 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20 BLE 30
22af0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
22b00 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 Module Name
22b10 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
22b20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 SQLITE_FUNCTION
22b30 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20 31
22b40 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 /* NULL
22b50 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d Function Nam
22b60 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 e */.#define S
22b70 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 QLITE_SAVEPOINT
22b80 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20 32
22b90 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 /* Operation
22ba0 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d Savepoint Nam
22bb0 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 e */.#define SQ
22bc0 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 LITE_COPY
22bd0 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 0 /
22be0 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 * No longer used
22bf0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
22c00 54 45 5f 52 45 43 55 52 53 49 56 45 20 20 20 20 TE_RECURSIVE
22c10 20 20 20 20 20 20 20 20 33 33 20 20 20 2f 2a 20 33 /*
22c20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
22c30 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
22c40 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 */../*.** CAPI3R
22c50 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 EF: Tracing And
22c60 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 Profiling Functi
22c70 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 ons.** METHOD: s
22c80 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 qlite3.**.** The
22c90 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 se routines regi
22ca0 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 ster callback fu
22cb0 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e nctions that can
22cc0 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 be used for.**
22cd0 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 tracing and prof
22ce0 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 iling the execut
22cf0 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 ion of SQL state
22d00 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ments..**.** ^Th
22d10 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 e callback funct
22d20 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 ion registered b
22d30 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 y sqlite3_trace(
22d40 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a ) is invoked at.
22d50 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 ** various times
22d60 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 when an SQL sta
22d70 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 tement is being
22d80 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f run by [sqlite3_
22d90 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 step()]..** ^The
22da0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 sqlite3_trace()
22db0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
22dc0 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d oked with a UTF-
22dd0 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 8 rendering of t
22de0 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d he.** SQL statem
22df0 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20 ent text as the
22e00 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 statement first
22e10 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 begins executing
22e20 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 ..** ^(Additiona
22e30 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 l sqlite3_trace(
22e40 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 ) callbacks migh
22e50 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 t occur.** as ea
22e60 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62 ch triggered sub
22e70 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 program is enter
22e80 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 ed. The callbac
22e90 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a ks for triggers.
22ea0 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 ** contain a UTF
22eb0 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 -8 SQL comment t
22ec0 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 hat identifies t
22ed0 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a he trigger.)^.**
22ee0 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
22ef0 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 TRACE_SIZE_LIMIT
22f00 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
22f10 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 ption can be use
22f20 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 d to limit.** th
22f30 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75 e length of [bou
22f40 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78 nd parameter] ex
22f50 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f pansion in the o
22f60 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33 utput of sqlite3
22f70 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 _trace()..**.**
22f80 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 ^The callback fu
22f90 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 nction registere
22fa0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f d by sqlite3_pro
22fb0 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 file() is invoke
22fc0 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c d.** as each SQL
22fd0 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 statement finis
22fe0 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 hes. ^The profi
22ff0 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 le callback cont
23000 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 ains.** the orig
23010 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 inal statement t
23020 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d ext and an estim
23030 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 ate of wall-cloc
23040 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 k time.** of how
23050 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 long that state
23060 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e ment took to run
23070 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 . ^The profile
23080 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 callback.** time
23090 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 is in units of
230a0 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 nanoseconds, how
230b0 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74 ever the current
230c0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a implementation.
230d0 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 ** is only capab
230e0 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e le of millisecon
230f0 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 d resolution so
23100 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69 the six least si
23110 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 gnificant.** dig
23120 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20 its in the time
23130 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e are meaningless.
23140 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e Future version
23150 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d s of SQLite.** m
23160 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65 ight provide gre
23170 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 ater resolution
23180 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20 on the profiler
23190 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a callback. The.*
231a0 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c * sqlite3_profil
231b0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 e() function is
231c0 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 considered exper
231d0 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a imental and is.*
231e0 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 * subject to cha
231f0 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 65 nge in future ve
23200 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
23210 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
23220 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 void *SQLITE_STD
23230 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74 72 61 CALL sqlite3_tra
23240 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 ce(sqlite3*, voi
23250 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a d(*xTrace)(void*
23260 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 ,const char*), v
23270 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 oid*);.SQLITE_AP
23280 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d I SQLITE_EXPERIM
23290 45 4e 54 41 4c 20 76 6f 69 64 20 2a 53 51 4c 49 ENTAL void *SQLI
232a0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
232b0 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 e3_profile(sqlit
232c0 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 e3*,. void(*xP
232d0 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f rofile)(void*,co
232e0 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 nst char*,sqlite
232f0 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 3_uint64), void*
23300 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
23310 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 EF: Query Progre
23320 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 ss Callbacks.**
23330 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a METHOD: sqlite3.
23340 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
23350 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 e3_progress_hand
23360 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 ler(D,N,X,P) int
23370 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68 erface causes th
23380 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 e callback.** fu
23390 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 nction X to be i
233a0 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 nvoked periodica
233b0 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 lly during long
233c0 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f running calls to
233d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 .** [sqlite3_exe
233e0 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 c()], [sqlite3_s
233f0 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 tep()] and [sqli
23400 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d te3_get_table()]
23410 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 for.** database
23420 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 connection D.
23430 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 An example use f
23440 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 or this.** inter
23450 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 face is to keep
23460 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75 a GUI updated du
23470 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 ring a large que
23480 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 ry..**.** ^The p
23490 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61 arameter P is pa
234a0 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 ssed through as
234b0 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 the only paramet
234c0 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 er to the .** ca
234d0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
234e0 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 X. ^The paramet
234f0 65 72 20 4e 20 69 73 20 74 68 65 20 61 70 70 72 er N is the appr
23500 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f oximate number o
23510 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d f .** [virtual m
23520 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69 achine instructi
23530 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76 ons] that are ev
23540 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20 aluated between
23550 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e successive.** in
23560 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 vocations of the
23570 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49 callback X. ^I
23580 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e f N is less than
23590 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70 72 one then the pr
235a0 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 ogress.** handle
235b0 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a r is disabled..*
235c0 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e *.** ^Only a sin
235d0 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e gle progress han
235e0 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 69 dler may be defi
235f0 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 ned at one time
23600 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 per.** [database
23610 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 connection]; se
23620 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 tting a new prog
23630 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e ress handler can
23640 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 cels the.** old
23650 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 one. ^Setting p
23660 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 arameter X to NU
23670 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 LL disables the
23680 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 progress handler
23690 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 ..** ^The progre
236a0 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c ss handler is al
236b0 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 73 so disabled by s
236c0 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 etting N to a va
236d0 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e lue less.** than
236e0 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 1..**.** ^If th
236f0 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 e progress callb
23700 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d ack returns non-
23710 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 zero, the operat
23720 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 ion is.** interr
23730 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 upted. This fea
23740 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 ture can be used
23750 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a to implement a.
23760 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 ** "Cancel" butt
23770 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 on on a GUI prog
23780 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e ress dialog box.
23790 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 .**.** The progr
237a0 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c ess handler call
237b0 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f back must not do
237c0 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 anything that w
237d0 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 ill modify.** th
237e0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
237f0 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b ction that invok
23800 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 ed the progress
23810 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 handler..** Note
23820 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 that [sqlite3_p
23830 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 repare_v2()] and
23840 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
23850 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 ] both modify th
23860 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 eir.** database
23870 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 connections for
23880 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 the meaning of "
23890 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 modify" in this
238a0 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f paragraph..**.*/
238b0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
238c0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
238d0 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 sqlite3_progress
238e0 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 _handler(sqlite3
238f0 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 *, int, int(*)(v
23900 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a oid*), void*);..
23910 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
23920 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 Opening A New Da
23930 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f tabase Connectio
23940 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 n.** CONSTRUCTOR
23950 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 : sqlite3.**.**
23960 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 ^These routines
23970 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 open an SQLite d
23980 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 atabase file as
23990 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 specified by the
239a0 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 .** filename ar
239b0 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c gument. ^The fil
239c0 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 ename argument i
239d0 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 s interpreted as
239e0 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 UTF-8 for.** sq
239f0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 lite3_open() and
23a00 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
23a10 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 () and as UTF-16
23a20 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 in the native b
23a30 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 yte.** order for
23a40 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 sqlite3_open16(
23a50 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 ). ^(A [database
23a60 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e connection] han
23a70 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a dle is usually.*
23a80 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 * returned in *p
23a90 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 pDb, even if an
23aa0 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 error occurs. T
23ab0 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f he only exceptio
23ac0 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 n is that.** if
23ad0 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 SQLite is unable
23ae0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d to allocate mem
23af0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 ory to hold the
23b00 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 [sqlite3] object
23b10 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c ,.** a NULL will
23b20 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f be written into
23b30 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f *ppDb instead o
23b40 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 f a pointer to t
23b50 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 he [sqlite3].**
23b60 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 object.)^ ^(If t
23b70 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f he database is o
23b80 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 pened (and/or cr
23b90 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75 eated) successfu
23ba0 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 lly, then.** [SQ
23bb0 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 LITE_OK] is retu
23bc0 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 rned. Otherwise
23bd0 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d an [error code]
23be0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 is returned.)^
23bf0 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ^The.** [sqlite3
23c00 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 _errmsg()] or [s
23c10 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 qlite3_errmsg16(
23c20 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 )] routines can
23c30 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 be used to obtai
23c40 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 n.** an English
23c50 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 language descrip
23c60 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f tion of the erro
23c70 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 r following a fa
23c80 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 ilure of any.**
23c90 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f of the sqlite3_o
23ca0 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a pen() routines..
23cb0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 **.** ^The defau
23cc0 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c lt encoding will
23cd0 20 62 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61 be UTF-8 for da
23ce0 74 61 62 61 73 65 73 20 63 72 65 61 74 65 64 20 tabases created
23cf0 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 using.** sqlite3
23d00 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 _open() or sqlit
23d10 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e e3_open_v2(). ^
23d20 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f The default enco
23d30 64 69 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73 ding for databas
23d40 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73 es.** created us
23d50 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e ing sqlite3_open
23d60 31 36 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46 16() will be UTF
23d70 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 -16 in the nativ
23d80 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a e byte order..**
23d90 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e .** Whether or n
23da0 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 ot an error occu
23db0 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 rs when it is op
23dc0 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a ened, resources.
23dd0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 ** associated wi
23de0 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 th the [database
23df0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e connection] han
23e00 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 dle should be re
23e10 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 leased by.** pas
23e20 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 sing it to [sqli
23e30 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 te3_close()] whe
23e40 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 n it is no longe
23e50 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a r required..**.*
23e60 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 * The sqlite3_op
23e70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 en_v2() interfac
23e80 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c e works like sql
23e90 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 ite3_open().** e
23ea0 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63 xcept that it ac
23eb0 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 cepts two additi
23ec0 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 onal parameters
23ed0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 for additional c
23ee0 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 ontrol.** over t
23ef0 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 he new database
23f00 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 connection. ^(T
23f10 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 he flags paramet
23f20 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 er to.** sqlite3
23f30 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 _open_v2() can t
23f40 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 ake one of.** th
23f50 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 e following thre
23f60 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e e values, option
23f70 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 ally combined wi
23f80 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 th the .** [SQLI
23f90 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d TE_OPEN_NOMUTEX]
23fa0 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 , [SQLITE_OPEN_F
23fb0 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 ULLMUTEX], [SQLI
23fc0 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 TE_OPEN_SHAREDCA
23fd0 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 CHE],.** [SQLITE
23fe0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 _OPEN_PRIVATECAC
23ff0 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c HE], and/or [SQL
24000 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c ITE_OPEN_URI] fl
24010 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c ags:)^.**.** <dl
24020 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 >.** ^(<dt>[SQLI
24030 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 TE_OPEN_READONLY
24040 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 ]</dt>.** <dd>Th
24050 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 e database is op
24060 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c ened in read-onl
24070 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 y mode. If the
24080 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f database does no
24090 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 t.** already exi
240a0 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 st, an error is
240b0 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e returned.</dd>)^
240c0 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 .**.** ^(<dt>[SQ
240d0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 LITE_OPEN_READWR
240e0 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 ITE]</dt>.** <dd
240f0 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 >The database is
24100 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 opened for read
24110 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 ing and writing
24120 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 if possible, or
24130 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 reading.** only
24140 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 if the file is w
24150 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 rite protected b
24160 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 y the operating
24170 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 system. In eith
24180 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 er.** case the d
24190 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 atabase must alr
241a0 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 eady exist, othe
241b0 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 rwise an error i
241c0 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e s returned.</dd>
241d0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b )^.**.** ^(<dt>[
241e0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
241f0 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 WRITE] | [SQLITE
24200 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 _OPEN_CREATE]</d
24210 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 t>.** <dd>The da
24220 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 tabase is opened
24230 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 for reading and
24240 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 writing, and is
24250 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 created if.** i
24260 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 t does not alrea
24270 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 dy exist. This i
24280 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 s the behavior t
24290 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 hat is always us
242a0 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 ed for.** sqlite
242b0 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 3_open() and sql
242c0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f ite3_open16().</
242d0 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a dd>)^.** </dl>.*
242e0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 *.** If the 3rd
242f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
24300 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 ite3_open_v2() i
24310 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 s not one of the
24320 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 .** combinations
24330 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 shown above opt
24340 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 ionally combined
24350 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b with other.** [
24360 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
24370 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 ONLY | SQLITE_OP
24380 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 EN_* bits].** th
24390 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 en the behavior
243a0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a is undefined..**
243b0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c .** ^If the [SQL
243c0 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 ITE_OPEN_NOMUTEX
243d0 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 ] flag is set, t
243e0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 hen the database
243f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f connection.** o
24400 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 pens in the mult
24410 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 i-thread [thread
24420 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e ing mode] as lon
24430 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d g as the single-
24440 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 thread.** mode h
24450 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 as not been set
24460 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 at compile-time
24470 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 or start-time.
24480 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 ^If the.** [SQLI
24490 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 TE_OPEN_FULLMUTE
244a0 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 X] flag is set t
244b0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 hen the database
244c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e connection open
244d0 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 s.** in the seri
244e0 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e alized [threadin
244f0 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 g mode] unless s
24500 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 ingle-thread was
24510 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 .** previously s
24520 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 elected at compi
24530 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 le-time or start
24540 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b -time..** ^The [
24550 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 SQLITE_OPEN_SHAR
24560 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 EDCACHE] flag ca
24570 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 uses the databas
24580 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 e connection to
24590 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 be.** eligible t
245a0 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 o use [shared ca
245b0 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 che mode], regar
245c0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 dless of whether
245d0 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a or not shared.*
245e0 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c * cache is enabl
245f0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ed using [sqlite
24600 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 3_enable_shared_
24610 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a cache()]. ^The.
24620 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ** [SQLITE_OPEN_
24630 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c PRIVATECACHE] fl
24640 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 ag causes the da
24650 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
24660 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 n to not.** part
24670 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 icipate in [shar
24680 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 ed cache mode] e
24690 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 ven if it is ena
246a0 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 bled..**.** ^The
246b0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
246c0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 r to sqlite3_ope
246d0 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 n_v2() is the na
246e0 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 me of the.** [sq
246f0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 lite3_vfs] objec
24700 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 t that defines t
24710 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 he operating sys
24720 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 tem interface th
24730 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 at.** the new da
24740 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
24750 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e n should use. ^
24760 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 If the fourth pa
24770 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 rameter is.** a
24780 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 NULL pointer the
24790 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 n the default [s
247a0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
247b0 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a ct is used..**.*
247c0 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 * ^If the filena
247d0 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 me is ":memory:"
247e0 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 , then a private
247f0 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d , temporary in-m
24800 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a emory database.*
24810 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 * is created for
24820 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e the connection.
24830 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 ^This in-memor
24840 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 y database will
24850 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 vanish when.** t
24860 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
24870 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 ection is closed
24880 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f . Future versio
24890 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 ns of SQLite mig
248a0 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f ht.** make use o
248b0 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 f additional spe
248c0 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 cial filenames t
248d0 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 hat begin with t
248e0 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 he ":" character
248f0 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d ..** It is recom
24900 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e mended that when
24910 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 a database file
24920 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f name actually do
24930 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a es begin with.**
24940 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 a ":" character
24950 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 you should pref
24960 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 ix the filename
24970 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 with a pathname
24980 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 such as.** "./"
24990 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 to avoid ambigui
249a0 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 ty..**.** ^If th
249b0 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e e filename is an
249c0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 empty string, t
249d0 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 hen a private, t
249e0 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 emporary.** on-d
249f0 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c isk database wil
24a00 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e l be created. ^
24a10 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74 This private dat
24a20 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a abase will be.**
24a30 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 automatically d
24a40 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 eleted as soon a
24a50 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 s the database c
24a60 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f onnection is clo
24a70 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 sed..**.** [[URI
24a80 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 filenames in sq
24a90 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c lite3_open()]] <
24aa0 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 h3>URI Filenames
24ab0 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 </h3>.**.** ^If
24ac0 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 [URI filename] i
24ad0 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 nterpretation is
24ae0 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 enabled, and th
24af0 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d e filename argum
24b00 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 ent.** begins wi
24b10 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e th "file:", then
24b20 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 the filename is
24b30 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 interpreted as
24b40 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 a URI. ^URI.** f
24b50 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 ilename interpre
24b60 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 tation is enable
24b70 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 d if the [SQLITE
24b80 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 _OPEN_URI] flag
24b90 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 is.** set in the
24ba0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 fourth argument
24bb0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e to sqlite3_open
24bc0 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 _v2(), or if it
24bd0 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 has.** been enab
24be0 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 led globally usi
24bf0 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 ng the [SQLITE_C
24c00 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f ONFIG_URI] optio
24c10 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 n with the.** [s
24c20 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
24c30 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 method or by th
24c40 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 e [SQLITE_USE_UR
24c50 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 I] compile-time
24c60 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 option..** As of
24c70 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
24c80 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 3.7.7, URI filen
24c90 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 ame interpretati
24ca0 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 on is turned off
24cb0 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 .** by default,
24cc0 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 but future relea
24cd0 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 ses of SQLite mi
24ce0 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 ght enable URI f
24cf0 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 ilename.** inter
24d00 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 pretation by def
24d10 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 ault. See "[URI
24d20 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 filenames]" for
24d30 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 additional.** i
24d40 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a nformation..**.*
24d50 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 * URI filenames
24d60 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 are parsed accor
24d70 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 ding to RFC 3986
24d80 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f . ^If the URI co
24d90 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 ntains an.** aut
24da0 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 hority, then it
24db0 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 must be either a
24dc0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f n empty string o
24dd0 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a r the string .**
24de0 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 "localhost". ^I
24df0 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 f the authority
24e00 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 is not an empty
24e10 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c string or "local
24e20 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 host", an .** er
24e30 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 ror is returned
24e40 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e to the caller. ^
24e50 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d The fragment com
24e60 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c ponent of a URI,
24e70 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c if .** present,
24e80 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a is ignored..**.
24e90 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 ** ^SQLite uses
24ea0 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 the path compone
24eb0 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 nt of the URI as
24ec0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
24ed0 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 disk file.** wh
24ee0 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 ich contains the
24ef0 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 database. ^If t
24f00 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 he path begins w
24f10 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 ith a '/' charac
24f20 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 ter, .** then it
24f30 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 is interpreted
24f40 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 as an absolute p
24f50 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 ath. ^If the pat
24f60 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e h does not begin
24f70 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 .** with a '/'
24f80 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 (meaning that th
24f90 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 e authority sect
24fa0 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 ion is omitted f
24fb0 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 rom the URI).**
24fc0 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 then the path is
24fd0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 interpreted as
24fe0 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e a relative path.
24ff0 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 .** ^(On window
25000 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d s, the first com
25010 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 ponent of an abs
25020 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 olute path .** i
25030 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66 s a drive specif
25040 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 ication (e.g. "C
25050 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 :").)^.**.** [[c
25060 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70 61 ore URI query pa
25070 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 rameters]].** Th
25080 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e e query componen
25090 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 t of a URI may c
250a0 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 ontain parameter
250b0 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 s that are inter
250c0 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 preted.** either
250d0 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c by SQLite itsel
250e0 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 f, or by a [VFS
250f0 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 | custom VFS imp
25100 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a lementation]..**
25110 20 53 51 4c 69 74 65 20 61 6e 64 20 69 74 73 20 SQLite and its
25120 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d built-in [VFSes]
25130 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a interpret the.*
25140 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 * following quer
25150 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a y parameters:.**
25160 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c .** <ul>.** <l
25170 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e i> <b>vfs</b>: ^
25180 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d 65 The "vfs" parame
25190 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 ter may be used
251a0 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 6e to specify the n
251b0 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 ame of.** a
251c0 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20 VFS object that
251d0 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65 provides the ope
251e0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e rating system in
251f0 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68 6f terface that sho
25200 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 uld.** be us
25210 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 ed to access the
25220 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f database file o
25230 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 n disk. ^If this
25240 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 option is set t
25250 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 o.** an empt
25260 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 66 y string the def
25270 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20 ault VFS object
25280 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66 is used. ^Specif
25290 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a ying an unknown.
252a0 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 6e ** VFS is an
252b0 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 error. ^If sqli
252c0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 te3_open_v2() is
252d0 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 66 used and the vf
252e0 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 s option is.**
252f0 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e present, then
25300 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66 69 the VFS specifi
25310 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e ed by the option
25320 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 takes precedenc
25330 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 e over.** th
25340 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 e value passed a
25350 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 s the fourth par
25360 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
25370 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 3_open_v2()..**.
25380 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 ** <li> <b>mod
25390 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 e</b>: ^(The mod
253a0 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 e parameter may
253b0 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 be set to either
253c0 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 "ro", "rw",.**
253d0 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d "rwc", or "m
253e0 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69 emory". Attempti
253f0 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20 ng to set it to
25400 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20 any other value
25410 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 is.** an err
25420 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 or)^. .** ^I
25430 66 20 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 f "ro" is specif
25440 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 ied, then the da
25450 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 tabase is opened
25460 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a for read-only .
25470 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a ** access, j
25480 75 73 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 ust as if the [S
25490 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f QLITE_OPEN_READO
254a0 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 NLY] flag had be
254b0 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a en set in the .*
254c0 2a 20 20 20 20 20 74 68 69 72 64 20 61 72 67 75 * third argu
254d0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f ment to sqlite3_
254e0 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 open_v2(). ^If t
254f0 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 he mode option i
25500 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 s set to .**
25510 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 "rw", then the
25520 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e database is open
25530 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 ed for read-writ
25540 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 e (but not creat
25550 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 e) .** acces
25560 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f s, as if SQLITE_
25570 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 OPEN_READWRITE (
25580 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f but not SQLITE_O
25590 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 PEN_CREATE) had
255a0 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 .** been set
255b0 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 . ^Value "rwc" i
255c0 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 s equivalent to
255d0 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a setting both .**
255e0 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e SQLITE_OPEN
255f0 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 _READWRITE and S
25600 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 QLITE_OPEN_CREAT
25610 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 E. ^If the mode
25620 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 option is.**
25630 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 set to "memory
25640 22 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69 " then a pure [i
25650 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 n-memory databas
25660 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72 65 e] that never re
25670 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 ads.** or wr
25680 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 ites from disk i
25690 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61 s used. ^It is a
256a0 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 n error to speci
256b0 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a fy a value for.*
256c0 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70 * the mode p
256d0 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 73 arameter that is
256e0 20 6c 65 73 73 20 72 65 73 74 72 69 63 74 69 76 less restrictiv
256f0 65 20 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 e than that spec
25700 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 ified by.**
25710 74 68 65 20 66 6c 61 67 73 20 70 61 73 73 65 64 the flags passed
25720 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 in the third pa
25730 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
25740 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a e3_open_v2()..**
25750 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 .** <li> <b>ca
25760 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 che</b>: ^The ca
25770 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 che parameter ma
25780 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 y be set to eith
25790 65 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a er "shared" or.*
257a0 2a 20 20 20 20 20 22 70 72 69 76 61 74 65 22 2e * "private".
257b0 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 ^Setting it to
257c0 22 73 68 61 72 65 64 22 20 69 73 20 65 71 75 69 "shared" is equi
257d0 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e valent to settin
257e0 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c g the.** SQL
257f0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 ITE_OPEN_SHAREDC
25800 41 43 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 ACHE bit in the
25810 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 flags argument p
25820 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 assed to.**
25830 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
25840 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 ). ^Setting the
25850 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 cache parameter
25860 74 6f 20 22 70 72 69 76 61 74 65 22 20 69 73 20 to "private" is
25870 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 .** equivale
25880 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 nt to setting th
25890 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 e SQLITE_OPEN_PR
258a0 49 56 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a IVATECACHE bit..
258b0 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 ** ^If sqlit
258c0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 e3_open_v2() is
258d0 75 73 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 used and the "ca
258e0 63 68 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 che" parameter i
258f0 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 s present in.**
25900 20 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 a URI filena
25910 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 me, its value ov
25920 65 72 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 errides any beha
25930 76 69 6f 72 20 72 65 71 75 65 73 74 65 64 20 62 vior requested b
25940 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 y setting.**
25950 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 SQLITE_OPEN_PRI
25960 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c VATECACHE or SQL
25970 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 ITE_OPEN_SHAREDC
25980 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a ACHE flag..**.**
25990 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f <li> <b>psow</
259a0 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 61 b>: ^The psow pa
259b0 72 61 6d 65 74 65 72 20 69 6e 64 69 63 61 74 65 rameter indicate
259c0 73 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 s whether or not
259d0 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 the.** [pow
259e0 65 72 73 61 66 65 20 6f 76 65 72 77 72 69 74 65 ersafe overwrite
259f0 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65 73 20 ] property does
25a00 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c or does not appl
25a10 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 y to the.**
25a20 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20 6f 6e storage media on
25a30 20 77 68 69 63 68 20 74 68 65 20 64 61 74 61 62 which the datab
25a40 61 73 65 20 66 69 6c 65 20 72 65 73 69 64 65 73 ase file resides
25a50 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 ..**.** <li> <b
25a60 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 >nolock</b>: ^Th
25a70 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74 e nolock paramet
25a80 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 er is a boolean
25a90 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 0a query parameter.
25aa0 2a 2a 20 20 20 20 20 77 68 69 63 68 20 69 66 20 ** which if
25ab0 73 65 74 20 64 69 73 61 62 6c 65 73 20 66 69 6c set disables fil
25ac0 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c e locking in rol
25ad0 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f lback journal mo
25ae0 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20 des. This.**
25af0 20 20 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20 is useful for
25b00 61 63 63 65 73 73 69 6e 67 20 61 20 64 61 74 61 accessing a data
25b10 62 61 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 79 base on a filesy
25b20 73 74 65 6d 20 74 68 61 74 20 64 6f 65 73 20 6e stem that does n
25b30 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f 72 ot.** suppor
25b40 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74 t locking. Caut
25b50 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 65 20 63 ion: Database c
25b60 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20 orruption might
25b70 72 65 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a result if two.**
25b80 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f or more pro
25b90 63 65 73 73 65 73 20 77 72 69 74 65 20 74 6f 20 cesses write to
25ba0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 the same databas
25bb0 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66 e and any one of
25bc0 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72 those.** pr
25bd0 6f 63 65 73 73 65 73 20 75 73 65 73 20 6e 6f 6c ocesses uses nol
25be0 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c ock=1..**.** <l
25bf0 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c i> <b>immutable<
25c00 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61 /b>: ^The immuta
25c10 62 6c 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 ble parameter is
25c20 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 a boolean query
25c30 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65 .** paramete
25c40 72 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 r that indicates
25c50 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 that the databa
25c60 73 65 20 66 69 6c 65 20 69 73 20 73 74 6f 72 65 se file is store
25c70 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64 d on.** read
25c80 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57 -only media. ^W
25c90 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 73 hen immutable is
25ca0 20 73 65 74 2c 20 53 51 4c 69 74 65 20 61 73 73 set, SQLite ass
25cb0 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a umes that the.**
25cc0 20 20 20 20 20 64 61 74 61 62 61 73 65 20 66 69 database fi
25cd0 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 le cannot be cha
25ce0 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 20 61 20 nged, even by a
25cf0 70 72 6f 63 65 73 73 20 77 69 74 68 20 68 69 67 process with hig
25d00 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 69 her.** privi
25d10 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 lege, and so the
25d20 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 database is ope
25d30 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e ned read-only an
25d40 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a d all locking.**
25d50 20 20 20 20 20 61 6e 64 20 63 68 61 6e 67 65 20 and change
25d60 64 65 74 65 63 74 69 6f 6e 20 69 73 20 64 69 73 detection is dis
25d70 61 62 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a abled. Caution:
25d80 20 53 65 74 74 69 6e 67 20 74 68 65 20 69 6d 6d Setting the imm
25d90 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72 utable.** pr
25da0 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 61 74 61 operty on a data
25db0 62 61 73 65 20 66 69 6c 65 20 74 68 61 74 20 64 base file that d
25dc0 6f 65 73 20 69 6e 20 66 61 63 74 20 63 68 61 6e oes in fact chan
25dd0 67 65 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a ge can result.**
25de0 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 63 in incorrec
25df0 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 t query results
25e00 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43 and/or [SQLITE_C
25e10 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a ORRUPT] errors..
25e20 2a 2a 20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a ** See also:
25e30 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 [SQLITE_IOCAP_I
25e40 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 MMUTABLE]..**
25e50 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a .** </ul>.**
25e60 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 .** ^Specifying
25e70 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d an unknown param
25e80 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 eter in the quer
25e90 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 y component of a
25ea0 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a URI is not an.*
25eb0 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 * error. Future
25ec0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
25ed0 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 ite might unders
25ee0 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 tand additional
25ef0 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 query.** paramet
25f00 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 ers. See "[quer
25f10 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 y parameters wit
25f20 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e h special meanin
25f30 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f g to SQLite]" fo
25f40 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 r.** additional
25f50 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a information..**.
25f60 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d ** [[URI filenam
25f70 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 e examples]] <h3
25f80 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 >URI filename ex
25f90 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a amples</h3>.**.*
25fa0 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d * <table border=
25fb0 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 "1" align=center
25fc0 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a cellpadding=5>.
25fd0 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 ** <tr><th> URI
25fe0 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 filenames <th> R
25ff0 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 esults.** <tr><t
26000 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 d> file:data.db
26010 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 <td> .**
26020 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 Open the file
26030 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 "data.db" in the
26040 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f current directo
26050 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 ry..** <tr><td>
26060 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f file:/home/fred/
26070 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 data.db<br>.**
26080 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f file:///
26090 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 home/fred/data.d
260a0 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 b <br> .**
260b0 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c file://local
260c0 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 host/home/fred/d
260d0 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e ata.db <br> <td>
260e0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 .** Op
260f0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
26100 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 file "/home/fred
26110 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 /data.db"..** <t
26120 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 r><td> file://da
26130 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 rkstar/home/fred
26140 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a /data.db <td> .*
26150 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 * An er
26160 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 ror. "darkstar"
26170 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 is not a recogni
26180 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a zed authority..*
26190 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d * <tr><td style=
261a0 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 "white-space:now
261b0 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 rap"> .**
261c0 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f file:///C:/Do
261d0 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 cuments%20and%20
261e0 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 Settings/fred/De
261f0 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a sktop/data.db.**
26200 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 <td> Window
26210 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 s only: Open the
26220 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 file "data.db"
26230 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f on fred's deskto
26240 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 p on drive.**
26250 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 C:. Note
26260 74 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63 that the %20 esc
26270 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 aping in this ex
26280 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 ample is not str
26290 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 ictly .**
262a0 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 necessary - s
262b0 70 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20 pace characters
262c0 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 can be used lite
262d0 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 rally.**
262e0 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d in URI filenam
262f0 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 es..** <tr><td>
26300 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 file:data.db?mod
26310 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 e=ro&cache=priva
26320 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 te <td> .**
26330 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 Open file "
26340 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 data.db" in the
26350 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 current director
26360 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 y for read-only
26370 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 access..**
26380 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f Regardless o
26390 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 f whether or not
263a0 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f shared-cache mo
263b0 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 de is enabled by
263c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 .** def
263d0 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 ault, use a priv
263e0 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 ate cache..** <t
263f0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d r><td> file:/hom
26400 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 e/fred/data.db?v
26410 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20 fs=unix-dotfile
26420 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 <td>.**
26430 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d Open file "/hom
26440 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e e/fred/data.db".
26450 20 55 73 65 20 74 68 65 20 73 70 65 63 69 61 6c Use the special
26460 20 56 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 69 VFS "unix-dotfi
26470 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 le".**
26480 74 68 61 74 20 75 73 65 73 20 64 6f 74 2d 66 69 that uses dot-fi
26490 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 les in place of
264a0 70 6f 73 69 78 20 61 64 76 69 73 6f 72 79 20 6c posix advisory l
264b0 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c ocking..** <tr><
264c0 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 td> file:data.db
264d0 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c ?mode=readonly <
264e0 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 td> .**
264f0 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 An error. "read
26500 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 only" is not a v
26510 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 alid option for
26520 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d the "mode" param
26530 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 eter..** </table
26540 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 >.**.** ^URI hex
26550 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 adecimal escape
26560 73 65 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 sequences (%HH)
26570 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 are supported wi
26580 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e thin the path an
26590 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f d.** query compo
265a0 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 nents of a URI.
265b0 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 A hexadecimal es
265c0 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f cape sequence co
265d0 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 nsists of a.** p
265e0 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 ercent sign - "%
265f0 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 " - followed by
26600 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 exactly two hexa
26610 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a decimal digits .
26620 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e ** specifying an
26630 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 octet value. ^B
26640 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f efore the path o
26650 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e r query componen
26660 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 ts of a.** URI f
26670 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 ilename are inte
26680 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 rpreted, they ar
26690 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 e encoded using
266a0 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a UTF-8 and all .*
266b0 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 * hexadecimal es
266c0 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 cape sequences r
266d0 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e eplaced by a sin
266e0 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e gle byte contain
266f0 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 ing the.** corre
26700 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 sponding octet.
26710 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 If this process
26720 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 generates an inv
26730 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 alid UTF-8 encod
26740 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 ing,.** the resu
26750 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 lts are undefine
26760 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 d..**.** <b>Note
26770 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 to Windows user
26780 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f s:</b> The enco
26790 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 ding used for th
267a0 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d e filename argum
267b0 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 ent.** of sqlite
267c0 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 3_open() and sql
267d0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d ite3_open_v2() m
267e0 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f ust be UTF-8, no
267f0 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f t whatever.** co
26800 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e depage is curren
26810 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 tly defined. Fi
26820 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 lenames containi
26830 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c ng international
26840 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d .** characters m
26850 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 ust be converted
26860 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 to UTF-8 prior
26870 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 to passing them
26880 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f into.** sqlite3_
26890 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 open() or sqlite
268a0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 3_open_v2()..**.
268b0 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 ** <b>Note to Wi
268c0 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 ndows Runtime us
268d0 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 ers:</b> The te
268e0 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 mporary director
268f0 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a y must be set.**
26900 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e prior to callin
26910 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 g sqlite3_open()
26920 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e or sqlite3_open
26930 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 _v2(). Otherwis
26940 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 e, various.** fe
26950 61 74 75 72 65 73 20 74 68 61 74 20 72 65 71 75 atures that requ
26960 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 ire the use of t
26970 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d emporary files m
26980 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 ay fail..**.** S
26990 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 ee also: [sqlite
269a0 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3_temp_directory
269b0 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ].*/.SQLITE_API
269c0 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 int SQLITE_STDCA
269d0 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 LL sqlite3_open(
269e0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 . const char *f
269f0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 ilename, /* Da
26a00 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 tabase filename
26a10 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c (UTF-8) */. sql
26a20 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 ite3 **ppDb
26a30 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c /* OUT: SQL
26a40 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f ite db handle */
26a50 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .);.SQLITE_API i
26a60 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c nt SQLITE_STDCAL
26a70 4c 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 L sqlite3_open16
26a80 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a (. const void *
26a90 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 filename, /* D
26aa0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 atabase filename
26ab0 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 (UTF-16) */. s
26ac0 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 qlite3 **ppDb
26ad0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 /* OUT: S
26ae0 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 QLite db handle
26af0 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 */.);.SQLITE_API
26b00 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
26b10 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e ALL sqlite3_open
26b20 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 _v2(. const cha
26b30 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f r *filename, /
26b40 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e * Database filen
26b50 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 ame (UTF-8) */.
26b60 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c sqlite3 **ppDb,
26b70 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a /* OUT:
26b80 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c SQLite db handl
26b90 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 e */. int flags
26ba0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f , /
26bb0 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e * Flags */. con
26bc0 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 st char *zVfs
26bd0 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 /* Name of
26be0 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 VFS module to us
26bf0 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 e */.);../*.** C
26c00 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 API3REF: Obtain
26c10 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50 Values For URI P
26c20 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 arameters.**.**
26c30 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74 These are utilit
26c40 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 y routines, usef
26c50 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d ul to VFS implem
26c60 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 entations, that
26c70 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 check.** to see
26c80 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69 if a database fi
26c90 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61 le was a URI tha
26ca0 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 t contained a sp
26cb0 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a ecific query .**
26cc0 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 parameter, and
26cd0 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 if so obtains th
26ce0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 e value of that
26cf0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e query parameter.
26d00 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 .**.** If F is t
26d10 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
26d20 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73 name pointer pas
26d30 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 sed into the xOp
26d40 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a en() method of .
26d50 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 ** a VFS impleme
26d60 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 ntation when the
26d70 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 flags parameter
26d80 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20 to xOpen() has
26d90 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 one or .** more
26da0 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f of the [SQLITE_O
26db0 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c PEN_URI] or [SQL
26dc0 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 ITE_OPEN_MAIN_DB
26dd0 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a ] bits set and.*
26de0 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20 * P is the name
26df0 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72 of the query par
26e00 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 ameter, then.**
26e10 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 sqlite3_uri_para
26e20 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 meter(F,P) retur
26e30 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 ns the value of
26e40 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 the P.** paramet
26e50 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20 er if it exists
26e60 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 or a NULL pointe
26e70 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 r if P does not
26e80 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 appear as a .**
26e90 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 query parameter
26ea0 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61 on F. If P is a
26eb0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 query parameter
26ec0 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 of F.** has no
26ed0 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 explicit value,
26ee0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 then sqlite3_uri
26ef0 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 _parameter(F,P)
26f00 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 returns.** a poi
26f10 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 nter to an empty
26f20 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 string..**.** T
26f30 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 he sqlite3_uri_b
26f40 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f oolean(F,P,B) ro
26f50 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68 utine assumes th
26f60 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 at P is a boolea
26f70 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61 n.** parameter a
26f80 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 nd returns true
26f90 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29 (1) or false (0)
26fa0 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 according to th
26fb0 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e e value.** of P.
26fc0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 The sqlite3_ur
26fd0 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 i_boolean(F,P,B)
26fe0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
26ff0 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68 65 true (1) if the
27000 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65 .** value of que
27010 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 ry parameter P i
27020 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 s one of "yes",
27030 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 "true", or "on"
27040 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f in any.** case o
27050 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 r if the value b
27060 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e egins with a non
27070 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 -zero number. T
27080 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 he .** sqlite3_u
27090 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 ri_boolean(F,P,B
270a0 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 ) routines retur
270b0 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 20 ns false (0) if
270c0 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 the value of.**
270d0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 query parameter
270e0 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 P is one of "no"
270f0 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f , "false", or "o
27100 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20 ff" in any case
27110 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c or.** if the val
27120 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 ue begins with a
27130 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 numeric zero.
27140 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75 If P is not a qu
27150 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ery.** parameter
27160 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20 on F or if the
27170 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f value of P is do
27180 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 es not match any
27190 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 of the.** above
271a0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 , then sqlite3_u
271b0 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 ri_boolean(F,P,B
271c0 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29 ) returns (B!=0)
271d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
271e0 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c te3_uri_int64(F,
271f0 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e P,D) routine con
27200 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20 verts the value
27210 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 of P into a.** 6
27220 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 4-bit signed int
27230 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 eger and returns
27240 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f that integer, o
27250 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f r D if P does no
27260 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20 t.** exist. If
27270 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 the value of P i
27280 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 s something othe
27290 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 r than an intege
272a0 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 r, then.** zero
272b0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 is returned..**
272c0 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55 .** If F is a NU
272d0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e LL pointer, then
272e0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 sqlite3_uri_par
272f0 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 ameter(F,P) retu
27300 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 rns NULL and.**
27310 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c sqlite3_uri_bool
27320 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 ean(F,P,B) retur
27330 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e ns B. If F is n
27340 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ot a NULL pointe
27350 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 r and.** is not
27360 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 a database file
27370 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 pathname pointer
27380 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 73 that SQLite pas
27390 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 sed into the xOp
273a0 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 en.** VFS method
273b0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 , then the behav
273c0 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74 ior of this rout
273d0 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64 ine is undefined
273e0 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a and probably.**
273f0 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f undesirable..*/
27400 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
27410 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 t char *SQLITE_S
27420 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 75 TDCALL sqlite3_u
27430 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e ri_parameter(con
27440 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 st char *zFilena
27450 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a me, const char *
27460 7a 50 61 72 61 6d 29 3b 0a 53 51 4c 49 54 45 5f zParam);.SQLITE_
27470 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 API int SQLITE_S
27480 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 75 TDCALL sqlite3_u
27490 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 ri_boolean(const
274a0 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f char *zFile, co
274b0 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d nst char *zParam
274c0 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b , int bDefault);
274d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 .SQLITE_API sqli
274e0 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 45 te3_int64 SQLITE
274f0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
27500 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 _uri_int64(const
27510 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 char*, const ch
27520 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 ar*, sqlite3_int
27530 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 64);.../*.** CAP
27540 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 I3REF: Error Cod
27550 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a es And Messages.
27560 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
27570 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 e3.**.** ^If the
27580 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 71 6c most recent sql
27590 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20 ite3_* API call
275a0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
275b0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
275c0 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61 69 6c nnection] D fail
275d0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c ed, then the sql
275e0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29 20 ite3_errcode(D)
275f0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 interface.** ret
27600 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 urns the numeric
27610 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f [result code] o
27620 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 r [extended resu
27630 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 61 lt code] for tha
27640 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e 0a 2a t.** API call..*
27650 2a 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 * If the most re
27660 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 77 61 cent API call wa
27670 73 20 73 75 63 63 65 73 73 66 75 6c 2c 0a 2a 2a s successful,.**
27680 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e then the return
27690 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 value from sqli
276a0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 te3_errcode() is
276b0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e undefined..** ^
276c0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 The sqlite3_exte
276d0 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a nded_errcode().*
276e0 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 * interface is t
276f0 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 he same except t
27700 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 hat it always re
27710 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 turns the .** [e
27720 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
27730 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 ode] even when e
27740 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
27750 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 odes are.** disa
27760 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 bled..**.** ^The
27770 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 sqlite3_errmsg(
27780 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 ) and sqlite3_er
27790 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 rmsg16() return
277a0 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 English-language
277b0 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 .** text that de
277c0 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f scribes the erro
277d0 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46 r, as either UTF
277e0 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 -8 or UTF-16 res
277f0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 pectively..** ^(
27800 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 Memory to hold t
27810 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 he error message
27820 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 string is manag
27830 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a ed internally..*
27840 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f * The applicatio
27850 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 n does not need
27860 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 to worry about f
27870 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c reeing the resul
27880 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 t..** However, t
27890 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 he error string
278a0 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 might be overwri
278b0 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 tten or dealloca
278c0 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 ted by.** subseq
278d0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 uent calls to ot
278e0 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 her SQLite inter
278f0 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 face functions.)
27900 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ^.**.** ^The sql
27910 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e ite3_errstr() in
27920 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
27930 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 the English-lang
27940 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 uage text.** tha
27950 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 t describes the
27960 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 [result code], a
27970 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 s UTF-8..** ^(Me
27980 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 mory to hold the
27990 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 error message s
279a0 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 tring is managed
279b0 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 internally.** a
279c0 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 nd must not be f
279d0 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70 6c reed by the appl
279e0 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a ication)^..**.**
279f0 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c When the serial
27a00 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 ized [threading
27a10 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c mode] is in use,
27a20 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 it might be the
27a30 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 .** case that a
27a40 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 second error occ
27a50 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 urs on a separat
27a60 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 e thread in betw
27a70 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 een.** the time
27a80 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72 of the first err
27a90 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 or and the call
27aa0 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 to these interfa
27ab0 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 ces..** When tha
27ac0 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 t happens, the s
27ad0 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c econd error will
27ae0 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e be reported sin
27af0 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 ce these.** inte
27b00 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 rfaces always re
27b10 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 port the most re
27b20 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f cent result. To
27b30 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 avoid.** this,
27b40 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 each thread can
27b50 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 obtain exclusive
27b60 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 use of the [dat
27b70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
27b80 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 ] D.** by invoki
27b90 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 ng [sqlite3_mute
27ba0 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 x_enter]([sqlite
27bb0 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 3_db_mutex](D))
27bc0 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 before beginning
27bd0 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 .** to use D and
27be0 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 invoking [sqlit
27bf0 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 e3_mutex_leave](
27c00 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 [sqlite3_db_mute
27c10 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 x](D)) after.**
27c20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 all calls to the
27c30 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 interfaces list
27c40 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 ed here are comp
27c50 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 leted..**.** If
27c60 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 an interface fai
27c70 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d ls with SQLITE_M
27c80 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e ISUSE, that mean
27c90 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a s the interface.
27ca0 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 ** was invoked i
27cb0 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 ncorrectly by th
27cc0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 e application.
27cd0 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 In that case, th
27ce0 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 e.** error code
27cf0 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 and message may
27d00 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 or may not be se
27d10 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 t..*/.SQLITE_API
27d20 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
27d30 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 72 72 63 ALL sqlite3_errc
27d40 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 ode(sqlite3 *db)
27d50 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
27d60 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
27d70 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 sqlite3_extended
27d80 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 _errcode(sqlite3
27d90 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 *db);.SQLITE_AP
27da0 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 I const char *SQ
27db0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
27dc0 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 ite3_errmsg(sqli
27dd0 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 te3*);.SQLITE_AP
27de0 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 I const void *SQ
27df0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
27e00 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 ite3_errmsg16(sq
27e10 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f lite3*);.SQLITE_
27e20 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a API const char *
27e30 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
27e40 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e qlite3_errstr(in
27e50 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
27e60 52 45 46 3a 20 50 72 65 70 61 72 65 64 20 53 74 REF: Prepared St
27e70 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a atement Object.*
27e80 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 * KEYWORDS: {pre
27e90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d pared statement}
27ea0 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 {prepared state
27eb0 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 ments}.**.** An
27ec0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 instance of this
27ed0 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e object represen
27ee0 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 ts a single SQL
27ef0 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a statement that.*
27f00 2a 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 69 * has been compi
27f10 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61 72 79 20 led into binary
27f20 66 6f 72 6d 20 61 6e 64 20 69 73 20 72 65 61 64 form and is read
27f30 79 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 y to be evaluate
27f40 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f d..**.** Think o
27f50 66 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 f each SQL state
27f60 6d 65 6e 74 20 61 73 20 61 20 73 65 70 61 72 61 ment as a separa
27f70 74 65 20 63 6f 6d 70 75 74 65 72 20 70 72 6f 67 te computer prog
27f80 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69 ram. The.** ori
27f90 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 20 69 ginal SQL text i
27fa0 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 s source code.
27fb0 41 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 A prepared state
27fc0 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 ment object .**
27fd0 69 73 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 is the compiled
27fe0 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20 20 41 6c object code. Al
27ff0 6c 20 53 51 4c 20 6d 75 73 74 20 62 65 20 63 6f l SQL must be co
28000 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a nverted into a.*
28010 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 * prepared state
28020 6d 65 6e 74 20 62 65 66 6f 72 65 20 69 74 20 63 ment before it c
28030 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a an be run..**.**
28040 20 54 68 65 20 6c 69 66 65 2d 63 79 63 6c 65 20 The life-cycle
28050 6f 66 20 61 20 70 72 65 70 61 72 65 64 20 73 74 of a prepared st
28060 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 atement object u
28070 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65 sually goes like
28080 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c this:.**.** <ol
28090 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 >.** <li> Create
280a0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 the prepared st
280b0 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 atement object u
280c0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 sing [sqlite3_pr
280d0 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 epare_v2()]..**
280e0 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 <li> Bind values
280f0 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 73 5d to [parameters]
28100 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 using the sqlit
28110 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 e3_bind_*().**
28120 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a interfaces..
28130 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 ** <li> Run the
28140 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b SQL by calling [
28150 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
28160 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 one or more time
28170 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 s..** <li> Reset
28180 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 the prepared st
28190 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 atement using [s
281a0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
281b0 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 then go back.**
281c0 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 to step 2.
281d0 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 Do this zero or
281e0 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 more times..**
281f0 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 <li> Destroy the
28200 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 object using [s
28210 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
28220 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a )]..** </ol>.*/.
28230 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
28240 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 qlite3_stmt sqli
28250 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a te3_stmt;../*.**
28260 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 CAPI3REF: Run-t
28270 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 ime Limits.** ME
28280 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a THOD: sqlite3.**
28290 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 .** ^(This inter
282a0 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 face allows the
282b0 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 size of various
282c0 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 constructs to be
282d0 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 limited.** on a
282e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 connection by c
282f0 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e onnection basis.
28300 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 The first para
28310 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 meter is the.**
28320 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
28330 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 tion] whose limi
28340 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f t is to be set o
28350 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a r queried. The.
28360 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 ** second parame
28370 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 ter is one of th
28380 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 e [limit categor
28390 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 ies] that define
283a0 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 a.** class of c
283b0 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 onstructs to be
283c0 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 size limited. T
283d0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
283e0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 er is the.** new
283f0 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 limit for that
28400 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a construct.)^.**.
28410 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c ** ^If the new l
28420 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 imit is a negati
28430 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c ve number, the l
28440 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 imit is unchange
28450 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 d..** ^(For each
28460 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 limit category
28470 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e SQLITE_LIMIT_<i>
28480 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 NAME</i> there i
28490 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 s a .** [limits
284a0 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 | hard upper bou
284b0 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f nd].** set at co
284c0 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 mpile-time by a
284d0 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d C preprocessor m
284e0 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b acro called.** [
284f0 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f limits | SQLITE_
28500 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d MAX_<i>NAME</i>]
28510 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 ..** (The "_LIMI
28520 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 T_" in the name
28530 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f is changed to "_
28540 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 MAX_".))^.** ^At
28550 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 tempts to increa
28560 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 se a limit above
28570 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20 its hard upper
28580 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c bound are.** sil
28590 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 ently truncated
285a0 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65 to the hard uppe
285b0 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e r bound..**.** ^
285c0 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 Regardless of wh
285d0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 ether or not the
285e0 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 limit was chang
285f0 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c ed, the .** [sql
28600 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e ite3_limit()] in
28610 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
28620 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 the prior value
28630 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a of the limit..**
28640 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 ^Hence, to find
28650 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c the current val
28660 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 ue of a limit wi
28670 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 thout changing i
28680 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 t,.** simply inv
28690 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 oke this interfa
286a0 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72 ce with the thir
286b0 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 d parameter set
286c0 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e to -1..**.** Run
286d0 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 -time limits are
286e0 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 intended for us
286f0 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e e in application
28700 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a s that manage.**
28710 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 both their own
28720 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 internal databas
28730 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 e and also datab
28740 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f ases that are co
28750 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 ntrolled.** by u
28760 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 ntrusted externa
28770 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 l sources. An e
28780 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 xample applicati
28790 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a on might be a.**
287a0 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 web browser tha
287b0 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 t has its own da
287c0 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 tabases for stor
287d0 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a ing history and.
287e0 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61 ** separate data
287f0 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 bases controlled
28800 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 by JavaScript a
28810 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e pplications down
28820 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 loaded.** off th
28830 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 e Internet. The
28840 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 internal databa
28850 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e ses can be given
28860 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 the.** large, d
28870 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 efault limits.
28880 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 Databases manage
28890 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f d by external so
288a0 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 urces can.** be
288b0 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c given much small
288c0 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e er limits design
288d0 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 ed to prevent a
288e0 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 denial of servic
288f0 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 e.** attack. De
28900 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 velopers might a
28910 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 lso want to use
28920 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 the [sqlite3_set
28930 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a _authorizer()].*
28940 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 * interface to f
28950 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 urther control u
28960 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 ntrusted SQL. T
28970 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 he size of the d
28980 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 atabase.** creat
28990 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 ed by an untrust
289a0 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 ed script can be
289b0 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 contained using
289c0 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 the.** [max_pag
289d0 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 e_count] [PRAGMA
289e0 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e ]..**.** New run
289f0 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 -time limit cate
28a00 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 gories may be ad
28a10 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 ded in future re
28a20 6c 65 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 leases..*/.SQLIT
28a30 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
28a40 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
28a50 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c _limit(sqlite3*,
28a60 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 int id, int new
28a70 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 Val);../*.** CAP
28a80 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 I3REF: Run-Time
28a90 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 Limit Categories
28aa0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c .** KEYWORDS: {l
28ab0 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b imit category} {
28ac0 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 *limit categorie
28ad0 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 s}.**.** These c
28ae0 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 onstants define
28af0 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 various performa
28b00 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 nce limits.** th
28b10 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 at can be lowere
28b20 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 d at run-time us
28b30 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d ing [sqlite3_lim
28b40 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 it()]..** The sy
28b50 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 nopsis of the me
28b60 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 anings of the va
28b70 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 rious limits is
28b80 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 shown below..**
28b90 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 Additional infor
28ba0 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 mation is availa
28bb0 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c ble at [limits |
28bc0 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 Limits in SQLit
28bd0 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a e]..**.** <dl>.*
28be0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 * [[SQLITE_LIMIT
28bf0 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e _LENGTH]] ^(<dt>
28c00 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e SQLITE_LIMIT_LEN
28c10 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e GTH</dt>.** <dd>
28c20 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 The maximum size
28c30 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f of any string o
28c40 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 r BLOB or table
28c50 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 row, in bytes.<d
28c60 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c d>)^.**.** [[SQL
28c70 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 ITE_LIMIT_SQL_LE
28c80 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c NGTH]] ^(<dt>SQL
28c90 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 ITE_LIMIT_SQL_LE
28ca0 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 NGTH</dt>.** <dd
28cb0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e >The maximum len
28cc0 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 gth of an SQL st
28cd0 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 atement, in byte
28ce0 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 s.</dd>)^.**.**
28cf0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 [[SQLITE_LIMIT_C
28d00 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 OLUMN]] ^(<dt>SQ
28d10 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d LITE_LIMIT_COLUM
28d20 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 N</dt>.** <dd>Th
28d30 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 e maximum number
28d40 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 of columns in a
28d50 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f table definitio
28d60 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 n or in the.** r
28d70 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b esult set of a [
28d80 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d SELECT] or the m
28d90 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
28da0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 columns in an i
28db0 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e ndex.** or in an
28dc0 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f ORDER BY or GRO
28dd0 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 UP BY clause.</d
28de0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c d>)^.**.** [[SQL
28df0 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 ITE_LIMIT_EXPR_D
28e00 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c EPTH]] ^(<dt>SQL
28e10 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 ITE_LIMIT_EXPR_D
28e20 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 EPTH</dt>.** <dd
28e30 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 >The maximum dep
28e40 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 th of the parse
28e50 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 tree on any expr
28e60 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a ession.</dd>)^.*
28e70 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 *.** [[SQLITE_LI
28e80 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c MIT_COMPOUND_SEL
28e90 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 ECT]] ^(<dt>SQLI
28ea0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e TE_LIMIT_COMPOUN
28eb0 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a D_SELECT</dt>.**
28ec0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
28ed0 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 number of terms
28ee0 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 in a compound S
28ef0 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e ELECT statement.
28f00 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b </dd>)^.**.** [[
28f10 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 SQLITE_LIMIT_VDB
28f20 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c E_OP]] ^(<dt>SQL
28f30 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f ITE_LIMIT_VDBE_O
28f40 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 P</dt>.** <dd>Th
28f50 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 e maximum number
28f60 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 of instructions
28f70 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 in a virtual ma
28f80 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a chine program.**
28f90 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 used to impleme
28fa0 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d nt an SQL statem
28fb0 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 ent. This limit
28fc0 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c is not currentl
28fd0 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 y.** enforced, t
28fe0 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 74 hough that might
28ff0 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d be added in som
29000 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 e future release
29010 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f of.** SQLite.</
29020 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 dd>)^.**.** [[SQ
29030 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 LITE_LIMIT_FUNCT
29040 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e ION_ARG]] ^(<dt>
29050 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e SQLITE_LIMIT_FUN
29060 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a CTION_ARG</dt>.*
29070 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
29080 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 m number of argu
29090 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 ments on a funct
290a0 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a ion.</dd>)^.**.*
290b0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 * [[SQLITE_LIMIT
290c0 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 _ATTACHED]] ^(<d
290d0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 t>SQLITE_LIMIT_A
290e0 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 TTACHED</dt>.**
290f0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
29100 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 number of [ATTAC
29110 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 H | attached dat
29120 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a abases].)^</dd>.
29130 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c **.** [[SQLITE_L
29140 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 IMIT_LIKE_PATTER
29150 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 N_LENGTH]].** ^(
29160 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
29170 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 _LIKE_PATTERN_LE
29180 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 NGTH</dt>.** <dd
29190 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e >The maximum len
291a0 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 gth of the patte
291b0 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 rn argument to t
291c0 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 he [LIKE] or.**
291d0 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 [GLOB] operators
291e0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b .</dd>)^.**.** [
291f0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 [SQLITE_LIMIT_VA
29200 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a RIABLE_NUMBER]].
29210 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f ** ^(<dt>SQLITE_
29220 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e LIMIT_VARIABLE_N
29230 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 UMBER</dt>.** <d
29240 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e d>The maximum in
29250 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e dex number of an
29260 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e y [parameter] in
29270 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e an SQL statemen
29280 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c t.)^.**.** [[SQL
29290 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 ITE_LIMIT_TRIGGE
292a0 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e R_DEPTH]] ^(<dt>
292b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 SQLITE_LIMIT_TRI
292c0 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a GGER_DEPTH</dt>.
292d0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
292e0 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 um depth of recu
292f0 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 rsion for trigge
29300 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a rs.</dd>)^.**.**
29310 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f [[SQLITE_LIMIT_
29320 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d WORKER_THREADS]]
29330 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
29340 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 MIT_WORKER_THREA
29350 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 DS</dt>.** <dd>T
29360 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 he maximum numbe
29370 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79 20 77 r of auxiliary w
29380 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20 74 68 orker threads th
29390 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b at a single.** [
293a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
293b0 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f nt] may start.</
293c0 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a dd>)^.** </dl>.*
293d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
293e0 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 _LIMIT_LENGTH
293f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
29400 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 0.#define SQLIT
29410 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 E_LIMIT_SQL_LENG
29420 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 TH
29430 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 1.#define SQLI
29440 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 TE_LIMIT_COLUMN
29450 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
29460 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 2.#define SQL
29470 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 ITE_LIMIT_EXPR_D
29480 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 EPTH
29490 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 3.#define SQ
294a0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f LITE_LIMIT_COMPO
294b0 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 UND_SELECT
294c0 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 4.#define S
294d0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 QLITE_LIMIT_VDBE
294e0 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20 _OP
294f0 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 5.#define
29500 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e SQLITE_LIMIT_FUN
29510 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 CTION_ARG
29520 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 6.#define
29530 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 SQLITE_LIMIT_AT
29540 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20 TACHED
29550 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 7.#defin
29560 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c e SQLITE_LIMIT_L
29570 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 IKE_PATTERN_LENG
29580 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 TH 8.#defi
29590 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
295a0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 VARIABLE_NUMBER
295b0 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 9.#def
295c0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
295d0 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 _TRIGGER_DEPTH
295e0 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 10.#de
295f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
29600 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 T_WORKER_THREADS
29610 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a 2f 11../
29620 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
29630 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 ompiling An SQL
29640 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 Statement.** KEY
29650 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 WORDS: {SQL stat
29660 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a ement compiler}.
29670 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
29680 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f e3.** CONSTRUCTO
29690 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a R: sqlite3_stmt.
296a0 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 **.** To execute
296b0 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 an SQL query, i
296c0 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 t must first be
296d0 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 compiled into a
296e0 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f byte-code.** pro
296f0 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f gram using one o
29700 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
29710 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 ..**.** The firs
29720 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 t argument, "db"
29730 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 , is a [database
29740 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 connection] obt
29750 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 ained from a.**
29760 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c prior successful
29770 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
29780 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 3_open()], [sqli
29790 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f te3_open_v2()] o
297a0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 r.** [sqlite3_op
297b0 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 en16()]. The da
297c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
297d0 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 n must not have
297e0 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a been closed..**.
297f0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 ** The second ar
29800 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 gument, "zSql",
29810 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 is the statement
29820 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c to be compiled,
29830 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 encoded.** as e
29840 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 ither UTF-8 or U
29850 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 TF-16. The sqli
29860 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e te3_prepare() an
29870 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 d sqlite3_prepar
29880 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 e_v2().** interf
29890 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 aces use UTF-8,
298a0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 and sqlite3_prep
298b0 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 are16() and sqli
298c0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
298d0 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 ().** use UTF-16
298e0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
298f0 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 nByte argument i
29900 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e s negative, then
29910 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 zSql is read up
29920 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 to the.** first
29930 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 zero terminator
29940 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 70 . ^If nByte is p
29950 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 69 74 ositive, then it
29960 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 is the.** numbe
29970 72 20 6f 66 20 62 79 74 65 73 20 72 65 61 64 20 r of bytes read
29980 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66 20 from zSql. ^If
29990 6e 42 79 74 65 20 69 73 20 7a 65 72 6f 2c 20 74 nByte is zero, t
299a0 68 65 6e 20 6e 6f 20 70 72 65 70 61 72 65 64 0a hen no prepared.
299b0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 ** statement is
299c0 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49 66 generated..** If
299d0 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 the caller know
299e0 73 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c s that the suppl
299f0 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 ied string is nu
29a00 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 l-terminated, th
29a10 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73 20 61 en.** there is a
29a20 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61 6e small performan
29a30 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 ce advantage to
29a40 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 passing an nByte
29a50 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a parameter that.
29a60 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 ** is the number
29a70 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 of bytes in the
29a80 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 input string <i
29a90 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a >including</i>.*
29aa0 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e * the nul-termin
29ab0 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 ator..**.** ^If
29ac0 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 pzTail is not NU
29ad0 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 LL then *pzTail
29ae0 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 is made to point
29af0 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 to the first by
29b00 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 te.** past the e
29b10 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 nd of the first
29b20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e SQL statement in
29b30 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f zSql. These ro
29b40 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 utines only.** c
29b50 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 ompile the first
29b60 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 statement in zS
29b70 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 ql, so *pzTail i
29b80 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 s left pointing
29b90 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 to.** what remai
29ba0 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a ns uncompiled..*
29bb0 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 *.** ^*ppStmt is
29bc0 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 left pointing t
29bd0 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 o a compiled [pr
29be0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
29bf0 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a ] that can be.**
29c00 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 executed using
29c10 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
29c20 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 . ^If there is
29c30 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d an error, *ppStm
29c40 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e t is set.** to N
29c50 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e ULL. ^If the in
29c60 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e put text contain
29c70 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 s no SQL (if the
29c80 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 input is an emp
29c90 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 ty.** string or
29ca0 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 a comment) then
29cb0 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 *ppStmt is set t
29cc0 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 o NULL..** The c
29cd0 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 alling procedure
29ce0 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 is responsible
29cf0 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 for deleting the
29d00 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c compiled.** SQL
29d10 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 statement using
29d20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
29d30 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 ze()] after it h
29d40 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 as finished with
29d50 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d it..** ppStmt m
29d60 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a ay not be NULL..
29d70 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 **.** ^On succes
29d80 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 s, the sqlite3_p
29d90 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 repare() family
29da0 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 of routines retu
29db0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a rn [SQLITE_OK];.
29dc0 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 ** otherwise an
29dd0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 [error code] is
29de0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
29df0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 The sqlite3_prep
29e00 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c are_v2() and sql
29e10 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
29e20 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 2() interfaces a
29e30 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 re.** recommende
29e40 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 d for all new pr
29e50 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 ograms. The two
29e60 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 older interfaces
29e70 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a are retained.**
29e80 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 for backwards c
29e90 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 ompatibility, bu
29ea0 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64 t their use is d
29eb0 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e iscouraged..** ^
29ec0 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 In the "v2" inte
29ed0 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 rfaces, the prep
29ee0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a ared statement.*
29ef0 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e * that is return
29f00 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 ed (the [sqlite3
29f10 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 _stmt] object) c
29f20 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f ontains a copy o
29f30 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 f the.** origina
29f40 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 l SQL text. This
29f50 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c causes the [sql
29f60 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 ite3_step()] int
29f70 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 erface to.** beh
29f80 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 ave differently
29f90 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a in three ways:.*
29fa0 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ol>.** <li
29fb0 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 >.** ^If the dat
29fc0 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 abase schema cha
29fd0 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 nges, instead of
29fe0 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 returning [SQLI
29ff0 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 TE_SCHEMA] as it
2a000 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 .** always used
2a010 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f to do, [sqlite3_
2a020 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 step()] will aut
2a030 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d omatically recom
2a040 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 pile the SQL.**
2a050 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 statement and tr
2a060 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 y to run it agai
2a070 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53 n. As many as [S
2a080 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41 QLITE_MAX_SCHEMA
2a090 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69 _RETRY].** retri
2a0a0 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65 es will occur be
2a0b0 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65 fore sqlite3_ste
2a0c0 70 28 29 20 67 69 76 65 73 20 75 70 20 61 6e 64 p() gives up and
2a0d0 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f returns an erro
2a0e0 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a r..** </li>.**.*
2a0f0 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 * <li>.** ^When
2a100 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c an error occurs,
2a110 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
2a120 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e ] will return on
2a130 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 e of the detaile
2a140 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 d.** [error code
2a150 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 s] or [extended
2a160 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e error codes]. ^
2a170 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 The legacy behav
2a180 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 ior was that.**
2a190 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
2a1a0 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 would only retu
2a1b0 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 rn a generic [SQ
2a1c0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 LITE_ERROR] resu
2a1d0 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 lt code.** and t
2a1e0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 he application w
2a1f0 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b ould have to mak
2a200 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 e a second call
2a210 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 to [sqlite3_rese
2a220 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 t()].** in order
2a230 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 to find the und
2a240 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 erlying cause of
2a250 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 the problem. Wi
2a260 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70 th the "v2" prep
2a270 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 are.** interface
2a280 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e s, the underlyin
2a290 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 g reason for the
2a2a0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e error is return
2a2b0 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a ed immediately..
2a2c0 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c ** </li>.**.** <
2a2d0 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 li>.** ^If the s
2a2e0 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f pecific value bo
2a2f0 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 und to [paramete
2a300 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 r | host paramet
2a310 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 er] in the .** W
2a320 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 HERE clause migh
2a330 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 t influence the
2a340 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 choice of query
2a350 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 plan for a state
2a360 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 ment,.** then th
2a370 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c e statement will
2a380 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c be automaticall
2a390 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 y recompiled, as
2a3a0 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65 if there had be
2a3b0 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 en .** a schema
2a3c0 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 change, on the f
2a3d0 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 irst [sqlite3_s
2a3e0 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c tep()] call foll
2a3f0 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 owing any change
2a400 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 .** to the [sqli
2a410 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 te3_bind_text |
2a420 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 bindings] of tha
2a430 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a t [parameter]. .
2a440 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 ** ^The specific
2a450 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d value of WHERE-
2a460 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 clause [paramete
2a470 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e r] might influen
2a480 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 ce the .** choic
2a490 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 e of query plan
2a4a0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 if the parameter
2a4b0 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e is the left-han
2a4c0 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b d side of a [LIK
2a4d0 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 E].** or [GLOB]
2a4e0 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 operator or if t
2a4f0 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 he parameter is
2a500 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 compared to an i
2a510 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a ndexed column.**
2a520 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 and the [SQLITE
2a530 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 _ENABLE_STAT3] c
2a540 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
2a550 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a on is enabled..*
2a560 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e * </li>.** </ol>
2a570 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
2a580 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c nt SQLITE_STDCAL
2a590 4c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 L sqlite3_prepar
2a5a0 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 e(. sqlite3 *db
2a5b0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 , /*
2a5c0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 Database handle
2a5d0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
2a5e0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 *zSql, /*
2a5f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 SQL statement, U
2a600 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a TF-8 encoded */.
2a610 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 int nByte,
2a620 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 /* Max
2a630 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a imum length of z
2a640 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f Sql in bytes. */
2a650 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 . sqlite3_stmt
2a660 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 **ppStmt, /* OU
2a670 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e T: Statement han
2a680 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 dle */. const c
2a690 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 har **pzTail
2a6a0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 /* OUT: Pointer
2a6b0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 to unused porti
2a6c0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b on of zSql */.);
2a6d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
2a6e0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
2a6f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
2a700 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2(. sqlite3 *db
2a710 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 , /*
2a720 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 Database handle
2a730 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
2a740 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 *zSql, /*
2a750 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 SQL statement, U
2a760 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a TF-8 encoded */.
2a770 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 int nByte,
2a780 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 /* Max
2a790 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a imum length of z
2a7a0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f Sql in bytes. */
2a7b0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 . sqlite3_stmt
2a7c0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 **ppStmt, /* OU
2a7d0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e T: Statement han
2a7e0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 dle */. const c
2a7f0 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 har **pzTail
2a800 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 /* OUT: Pointer
2a810 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 to unused porti
2a820 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b on of zSql */.);
2a830 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
2a840 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
2a850 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
2a860 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c (. sqlite3 *db,
2a870 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 /* D
2a880 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a atabase handle *
2a890 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a /. const void *
2a8a0 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 zSql, /* S
2a8b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 QL statement, UT
2a8c0 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a F-16 encoded */.
2a8d0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 int nByte,
2a8e0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 /* Max
2a8f0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a imum length of z
2a900 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f Sql in bytes. */
2a910 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 . sqlite3_stmt
2a920 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 **ppStmt, /* OU
2a930 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e T: Statement han
2a940 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 dle */. const v
2a950 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 oid **pzTail
2a960 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 /* OUT: Pointer
2a970 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 to unused porti
2a980 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b on of zSql */.);
2a990 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
2a9a0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
2a9b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
2a9c0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a _v2(. sqlite3 *
2a9d0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f db, /
2a9e0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c * Database handl
2a9f0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 e */. const voi
2aa00 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f d *zSql, /
2aa10 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c * SQL statement,
2aa20 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 UTF-16 encoded
2aa30 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 */. int nByte,
2aa40 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
2aa50 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f Maximum length o
2aa60 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e f zSql in bytes.
2aa70 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 */. sqlite3_st
2aa80 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a mt **ppStmt, /*
2aa90 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 OUT: Statement
2aaa0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
2aab0 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 t void **pzTail
2aac0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e /* OUT: Poin
2aad0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f ter to unused po
2aae0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f rtion of zSql */
2aaf0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .);../*.** CAPI3
2ab00 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 REF: Retrieving
2ab10 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a Statement SQL.**
2ab20 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
2ab30 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 _stmt.**.** ^Thi
2ab40 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 s interface can
2ab50 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 be used to retri
2ab60 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 eve a saved copy
2ab70 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c of the original
2ab80 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 .** SQL text use
2ab90 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 d to create a [p
2aba0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2abb0 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65 t] if that state
2abc0 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 ment was.** comp
2abd0 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 iled using eithe
2abe0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 r [sqlite3_prepa
2abf0 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c re_v2()] or [sql
2ac00 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
2ac10 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 2()]..*/.SQLITE_
2ac20 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a API const char *
2ac30 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
2ac40 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 qlite3_sql(sqlit
2ac50 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b e3_stmt *pStmt);
2ac60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2ac70 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 : Determine If A
2ac80 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 n SQL Statement
2ac90 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62 Writes The Datab
2aca0 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 ase.** METHOD: s
2acb0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a qlite3_stmt.**.*
2acc0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 * ^The sqlite3_s
2acd0 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 tmt_readonly(X)
2ace0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
2acf0 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f s true (non-zero
2ad00 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 ) if.** and only
2ad10 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 if the [prepare
2ad20 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d d statement] X m
2ad30 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63 akes no direct c
2ad40 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 hanges to.** the
2ad50 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 content of the
2ad60 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a database file..*
2ad70 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b *.** Note that [
2ad80 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
2ad90 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ned SQL function
2ada0 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 s] or.** [virtua
2adb0 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 l tables] might
2adc0 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 change the datab
2add0 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61 ase indirectly a
2ade0 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74 2e s a side effect.
2adf0 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d .** ^(For exam
2ae00 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 ple, if an appli
2ae10 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 cation defines a
2ae20 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 function "eval(
2ae30 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c )" that .** call
2ae40 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 s [sqlite3_exec(
2ae50 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c )], then the fol
2ae60 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65 lowing SQL state
2ae70 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 ment would.** ch
2ae80 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 ange the databas
2ae90 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73 e file through s
2aea0 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a ide-effects:.**.
2aeb0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
2aec0 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 pre>.** SELEC
2aed0 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46 T eval('DELETE F
2aee0 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32 ROM t1') FROM t2
2aef0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f ;.** </pre></blo
2af00 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 ckquote>.**.** B
2af10 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20 5b ut because the [
2af20 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e SELECT] statemen
2af30 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 t does not chang
2af40 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 e the database f
2af50 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c ile.** directly,
2af60 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 sqlite3_stmt_re
2af70 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 adonly() would s
2af80 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65 till return true
2af90 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 .)^.**.** ^Trans
2afa0 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 action control s
2afb0 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61 tatements such a
2afc0 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d s [BEGIN], [COMM
2afd0 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c IT], [ROLLBACK],
2afe0 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c .** [SAVEPOINT],
2aff0 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 and [RELEASE] c
2b000 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d ause sqlite3_stm
2b010 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 t_readonly() to
2b020 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 return true,.**
2b030 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d since the statem
2b040 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20 ents themselves
2b050 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 do not actually
2b060 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62 modify the datab
2b070 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 ase but.** rathe
2b080 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 r they control t
2b090 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 he timing of whe
2b0a0 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e n other statemen
2b0b0 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a ts modify the .*
2b0c0 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68 * database. ^Th
2b0d0 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b e [ATTACH] and [
2b0e0 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e DETACH] statemen
2b0f0 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a ts also cause.**
2b100 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 sqlite3_stmt_re
2b110 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 adonly() to retu
2b120 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77 rn true since, w
2b130 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65 hile those state
2b140 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 ments.** change
2b150 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f the configuratio
2b160 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 n of a database
2b170 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 connection, they
2b180 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a do not make .**
2b190 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 changes to the
2b1a0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 content of the d
2b1b0 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e atabase files on
2b1c0 20 64 69 73 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 disk..*/.SQLITE
2b1d0 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f _API int SQLITE_
2b1e0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
2b1f0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 stmt_readonly(sq
2b200 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d lite3_stmt *pStm
2b210 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
2b220 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 REF: Determine I
2b230 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 f A Prepared Sta
2b240 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20 tement Has Been
2b250 52 65 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a Reset.** METHOD:
2b260 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a sqlite3_stmt.**
2b270 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
2b280 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e _stmt_busy(S) in
2b290 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
2b2a0 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 true (non-zero)
2b2b0 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 if the.** [prepa
2b2c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
2b2d0 20 68 61 73 20 62 65 65 6e 20 73 74 65 70 70 65 has been steppe
2b2e0 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 d at least once
2b2f0 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 using .** [sqlit
2b300 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20 e3_step(S)] but
2b310 68 61 73 20 6e 65 69 74 68 65 72 20 72 75 6e 20 has neither run
2b320 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 to completion (r
2b330 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 eturned.** [SQLI
2b340 54 45 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 TE_DONE] from [s
2b350 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 29 qlite3_step(S)])
2b360 20 6e 6f 72 0a 2a 2a 20 62 65 65 6e 20 72 65 73 nor.** been res
2b370 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 et using [sqlite
2b380 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 3_reset(S)]. ^T
2b390 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f he sqlite3_stmt_
2b3a0 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 busy(S).** inter
2b3b0 66 61 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c face returns fal
2b3c0 73 65 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c se if S is a NUL
2b3d0 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 L pointer. If S
2b3e0 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 is not a .** NU
2b3f0 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 LL pointer and i
2b400 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 s not a pointer
2b410 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70 to a valid [prep
2b420 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a ared statement].
2b430 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 ** object, then
2b440 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 the behavior is
2b450 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 undefined and pr
2b460 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 obably undesirab
2b470 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 le..**.** This i
2b480 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 nterface can be
2b490 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 used in combinat
2b4a0 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 ion [sqlite3_nex
2b4b0 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 t_stmt()].** to
2b4c0 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61 locate all prepa
2b4d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61 red statements a
2b4e0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 ssociated with a
2b4f0 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f database .** co
2b500 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72 nnection that ar
2b510 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 e in need of bei
2b520 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69 73 20 ng reset. This
2b530 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 can be used,.**
2b540 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 for example, in
2b550 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 diagnostic routi
2b560 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f nes to search fo
2b570 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 r prepared .** s
2b580 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61 tatements that a
2b590 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 re holding a tra
2b5a0 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a nsaction open..*
2b5b0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
2b5c0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
2b5d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 sqlite3_stmt_bus
2b5e0 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 y(sqlite3_stmt*)
2b5f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2b600 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 F: Dynamically T
2b610 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 yped Value Objec
2b620 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b t.** KEYWORDS: {
2b630 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
2b640 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 3_value} {unprot
2b650 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
2b660 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 lue}.**.** SQLit
2b670 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 e uses the sqlit
2b680 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 e3_value object
2b690 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c to represent all
2b6a0 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 values.** that
2b6b0 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e can be stored in
2b6c0 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c a database tabl
2b6d0 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 e. SQLite uses d
2b6e0 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a ynamic typing.**
2b6f0 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 for the values
2b700 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c it stores. ^Val
2b710 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 ues stored in sq
2b720 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
2b730 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e cts.** can be in
2b740 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 tegers, floating
2b750 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 point values, s
2b760 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f trings, BLOBs, o
2b770 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e r NULL..**.** An
2b780 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
2b790 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 bject may be eit
2b7a0 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 her "protected"
2b7b0 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 or "unprotected"
2b7c0 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 ..** Some interf
2b7d0 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 aces require a p
2b7e0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
2b7f0 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 _value. Other i
2b800 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c nterfaces.** wil
2b810 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 l accept either
2b820 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 a protected or a
2b830 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 n unprotected sq
2b840 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 lite3_value..**
2b850 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 Every interface
2b860 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c that accepts sql
2b870 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d ite3_value argum
2b880 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a ents specifies.*
2b890 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 * whether or not
2b8a0 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 it requires a p
2b8b0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
2b8c0 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20 _value. The.**
2b8d0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 [sqlite3_value_d
2b8e0 75 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 up()] interface
2b8f0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 can be used to c
2b900 6f 6e 73 74 72 75 63 74 20 61 20 6e 65 77 20 0a onstruct a new .
2b910 2a 2a 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c ** protected sql
2b920 69 74 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20 ite3_value from
2b930 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 an unprotected s
2b940 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a qlite3_value..**
2b950 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 .** The terms "p
2b960 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 rotected" and "u
2b970 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 nprotected" refe
2b980 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 r to whether or
2b990 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 not.** a mutex i
2b9a0 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 s held. An inte
2b9b0 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 rnal mutex is he
2b9c0 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 ld for a protect
2b9d0 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 ed.** sqlite3_va
2b9e0 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e lue object but n
2b9f0 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 o mutex is held
2ba00 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 for an unprotect
2ba10 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 ed.** sqlite3_va
2ba20 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 lue object. If
2ba30 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
2ba40 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d ed to be single-
2ba50 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 threaded.** (wit
2ba60 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 h [SQLITE_THREAD
2ba70 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 SAFE=0] and with
2ba80 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 [sqlite3_thread
2ba90 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e safe()] returnin
2baa0 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 g 0).** or if SQ
2bab0 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f Lite is run in o
2bac0 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 ne of reduced mu
2bad0 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 tex modes .** [S
2bae0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e QLITE_CONFIG_SIN
2baf0 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 GLETHREAD] or [S
2bb00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c QLITE_CONFIG_MUL
2bb10 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 TITHREAD].** the
2bb20 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 n there is no di
2bb30 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 stinction betwee
2bb40 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 n protected and
2bb50 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 unprotected.** s
2bb60 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
2bb70 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 ects and they ca
2bb80 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 n be used interc
2bb90 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 hangeably. Howe
2bba0 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 ver,.** for maxi
2bbb0 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 mum code portabi
2bbc0 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d lity it is recom
2bbd0 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c mended that appl
2bbe0 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c ications.** stil
2bbf0 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 l make the disti
2bc00 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 nction between p
2bc10 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 rotected and unp
2bc20 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 rotected.** sqli
2bc30 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
2bc40 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 s even when not
2bc50 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 strictly require
2bc60 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 d..**.** ^The sq
2bc70 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
2bc80 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73 cts that are pas
2bc90 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 sed as parameter
2bca0 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d s into the.** im
2bcb0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
2bcc0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 [application-def
2bcd0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f ined SQL functio
2bce0 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 ns] are protecte
2bcf0 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 d..** ^The sqlit
2bd00 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 e3_value object
2bd10 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b returned by.** [
2bd20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 sqlite3_column_v
2bd30 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f alue()] is unpro
2bd40 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f tected..** Unpro
2bd50 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
2bd60 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 alue objects may
2bd70 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 only be used wi
2bd80 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 th.** [sqlite3_r
2bd90 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 esult_value()] a
2bda0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 nd [sqlite3_bind
2bdb0 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 _value()]..** Th
2bdc0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 e [sqlite3_value
2bdd0 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f _blob | sqlite3_
2bde0 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 value_type()] fa
2bdf0 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 mily of.** inter
2be00 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 faces require pr
2be10 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
2be20 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a value objects..*
2be30 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
2be40 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c Mem sqlite3_val
2be50 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 ue;../*.** CAPI3
2be60 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f REF: SQL Functio
2be70 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 n Context Object
2be80 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 .**.** The conte
2be90 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 xt in which an S
2bea0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 QL function exec
2beb0 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 utes is stored i
2bec0 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f n an.** sqlite3_
2bed0 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 context object.
2bee0 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 ^A pointer to a
2bef0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 n sqlite3_contex
2bf00 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 t object.** is a
2bf10 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61 lways first para
2bf20 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 meter to [applic
2bf30 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 ation-defined SQ
2bf40 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a L functions]..**
2bf50 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
2bf60 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e -defined SQL fun
2bf70 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 ction implementa
2bf80 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 tion will pass t
2bf90 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 his.** pointer t
2bfa0 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c hrough into call
2bfb0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 s to [sqlite3_re
2bfc0 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 sult_int | sqlit
2bfd0 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a e3_result()],.**
2bfe0 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 [sqlite3_aggreg
2bff0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 ate_context()],
2c000 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 [sqlite3_user_da
2c010 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 ta()],.** [sqlit
2c020 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 e3_context_db_ha
2c030 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 ndle()], [sqlite
2c040 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 3_get_auxdata()]
2c050 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c ,.** and/or [sql
2c060 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 ite3_set_auxdata
2c070 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ()]..*/.typedef
2c080 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 struct sqlite3_c
2c090 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 ontext sqlite3_c
2c0a0 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ontext;../*.** C
2c0b0 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 API3REF: Binding
2c0c0 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 Values To Prepa
2c0d0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a red Statements.*
2c0e0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 * KEYWORDS: {hos
2c0f0 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f t parameter} {ho
2c100 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b st parameters} {
2c110 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e host parameter n
2c120 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 ame}.** KEYWORDS
2c130 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 : {SQL parameter
2c140 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 } {SQL parameter
2c150 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 s} {parameter bi
2c160 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44 nding}.** METHOD
2c170 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a : sqlite3_stmt.*
2c180 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 *.** ^(In the SQ
2c190 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 L statement text
2c1a0 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 input to [sqlit
2c1b0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
2c1c0 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 and its variant
2c1d0 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d s,.** literals m
2c1e0 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 ay be replaced b
2c1f0 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 y a [parameter]
2c200 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 that matches one
2c210 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a of following.**
2c220 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a templates:.**.*
2c230 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 * <ul>.** <li>
2c240 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a ?.** <li> ?NNN.
2c250 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a ** <li> :VVV.**
2c260 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c <li> @VVV.** <
2c270 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 li> $VVV.** </u
2c280 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 l>.**.** In the
2c290 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c templates above,
2c2a0 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 NNN represents
2c2b0 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 an integer liter
2c2c0 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 al,.** and VVV r
2c2d0 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 epresents an alp
2c2e0 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 hanumeric identi
2c2f0 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 fier.)^ ^The va
2c300 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a lues of these.**
2c310 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 parameters (als
2c320 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 o called "host p
2c330 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 arameter names"
2c340 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 or "SQL paramete
2c350 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 rs").** can be s
2c360 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c et using the sql
2c370 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f ite3_bind_*() ro
2c380 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 utines defined h
2c390 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ere..**.** ^The
2c3a0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 first argument t
2c3b0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 o the sqlite3_bi
2c3c0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 nd_*() routines
2c3d0 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 is always.** a p
2c3e0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 ointer to the [s
2c3f0 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a qlite3_stmt] obj
2c400 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f ect returned fro
2c410 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 m.** [sqlite3_pr
2c420 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 epare_v2()] or i
2c430 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a ts variants..**.
2c440 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 ** ^The second a
2c450 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 rgument is the i
2c460 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 ndex of the SQL
2c470 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 parameter to be
2c480 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 set..** ^The lef
2c490 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 tmost SQL parame
2c4a0 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 ter has an index
2c4b0 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 of 1. ^When th
2c4c0 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 e same named.**
2c4d0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 SQL parameter is
2c4e0 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 used more than
2c4f0 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 once, second and
2c500 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f subsequent.** o
2c510 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 ccurrences have
2c520 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 the same index a
2c530 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 s the first occu
2c540 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 rrence..** ^The
2c550 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 index for named
2c560 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 parameters can b
2c570 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e e looked up usin
2c580 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 g the.** [sqlite
2c590 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
2c5a0 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 _index()] API if
2c5b0 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 desired. ^The
2c5c0 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e index.** for "?N
2c5d0 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 NN" parameters i
2c5e0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e s the value of N
2c5f0 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 NN..** ^The NNN
2c600 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 value must be be
2c610 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 tween 1 and the
2c620 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 [sqlite3_limit()
2c630 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b ].** parameter [
2c640 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 SQLITE_LIMIT_VAR
2c650 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 IABLE_NUMBER] (d
2c660 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 efault value: 99
2c670 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 9)..**.** ^The t
2c680 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 hird argument is
2c690 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 the value to bi
2c6a0 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 nd to the parame
2c6b0 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ter..** ^If the
2c6c0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
2c6d0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f to sqlite3_bind_
2c6e0 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 text() or sqlite
2c6f0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 3_bind_text16().
2c700 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 ** or sqlite3_bi
2c710 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e nd_blob() is a N
2c720 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e ULL pointer then
2c730 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 the fourth para
2c740 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f meter.** is igno
2c750 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20 red and the end
2c760 72 65 73 75 6c 74 20 69 73 20 74 68 65 20 73 61 result is the sa
2c770 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69 me as sqlite3_bi
2c780 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a nd_null()..**.**
2c790 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 ^(In those rout
2c7a0 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 ines that have a
2c7b0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 fourth argument
2c7c0 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 , its value is t
2c7d0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 he.** number of
2c7e0 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 bytes in the par
2c7f0 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 ameter. To be c
2c800 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 lear: the value
2c810 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 is the.** number
2c820 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e of <u>bytes</u>
2c830 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e in the value, n
2c840 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ot the number of
2c850 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a characters.)^.*
2c860 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 * ^If the fourth
2c870 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
2c880 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 lite3_bind_text(
2c890 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e ) or sqlite3_bin
2c8a0 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 d_text16().** is
2c8b0 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 negative, then
2c8c0 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 the length of th
2c8d0 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 e string is.** t
2c8e0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
2c8f0 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 es up to the fir
2c900 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 st zero terminat
2c910 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f or..** If the fo
2c920 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 urth parameter t
2c930 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 o sqlite3_bind_b
2c940 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 76 lob() is negativ
2c950 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 e, then.** the b
2c960 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 ehavior is undef
2c970 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f ined..** If a no
2c980 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74 n-negative fourt
2c990 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 h parameter is p
2c9a0 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74 rovided to sqlit
2c9b0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a e3_bind_text().*
2c9c0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e * or sqlite3_bin
2c9d0 64 5f 74 65 78 74 31 36 28 29 20 6f 72 20 73 71 d_text16() or sq
2c9e0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 lite3_bind_text6
2c9f0 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74 4() then.** that
2ca00 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 parameter must
2ca10 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 be the byte offs
2ca20 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20 et.** where the
2ca30 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 NUL terminator w
2ca40 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d ould occur assum
2ca50 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77 ing the string w
2ca60 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 ere NUL.** termi
2ca70 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e nated. If any N
2ca80 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 UL characters oc
2ca90 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73 cur at byte offs
2caa0 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a ets less than .*
2cab0 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 * the value of t
2cac0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
2cad0 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73 ter then the res
2cae0 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61 ulting string va
2caf0 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 lue will.** cont
2cb00 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c ain embedded NUL
2cb10 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f s. The result o
2cb20 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e f expressions in
2cb30 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a volving strings.
2cb40 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 ** with embedded
2cb50 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e NULs is undefin
2cb60 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 ed..**.** ^The f
2cb70 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f ifth argument to
2cb80 20 74 68 65 20 42 4c 4f 42 20 61 6e 64 20 73 74 the BLOB and st
2cb90 72 69 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e 74 ring binding int
2cba0 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 61 20 erfaces.** is a
2cbb0 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 destructor used
2cbc0 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 to dispose of th
2cbd0 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 e BLOB or.** str
2cbe0 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 ing after SQLite
2cbf0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 has finished wi
2cc00 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 th it. ^The des
2cc10 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 tructor is calle
2cc20 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 d.** to dispose
2cc30 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 of the BLOB or s
2cc40 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 tring even if th
2cc50 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41 e call to bind A
2cc60 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66 PI fails..** ^If
2cc70 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d the fifth argum
2cc80 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 ent is.** the sp
2cc90 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c ecial value [SQL
2cca0 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 ITE_STATIC], the
2ccb0 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 n SQLite assumes
2ccc0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 that the.** inf
2ccd0 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 ormation is in s
2cce0 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 tatic, unmanaged
2ccf0 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 space and does
2cd00 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 not need to be f
2cd10 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 reed..** ^If the
2cd20 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 fifth argument
2cd30 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 has the value [S
2cd40 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d QLITE_TRANSIENT]
2cd50 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 , then.** SQLite
2cd60 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 makes its own p
2cd70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 rivate copy of t
2cd80 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 he data immediat
2cd90 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 ely, before.** t
2cda0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
2cdb0 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 *() routine retu
2cdc0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 rns..**.** ^The
2cdd0 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 sixth argument t
2cde0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 o sqlite3_bind_t
2cdf0 65 78 74 36 34 28 29 20 6d 75 73 74 20 62 65 20 ext64() must be
2ce00 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 one of.** [SQLIT
2ce10 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 E_UTF8], [SQLITE
2ce20 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 _UTF16], [SQLITE
2ce30 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 _UTF16BE], or [S
2ce40 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a QLITE_UTF16LE].*
2ce50 2a 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 * to specify the
2ce60 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 encoding of the
2ce70 20 74 65 78 74 20 69 6e 20 74 68 65 20 74 68 69 text in the thi
2ce80 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 rd parameter. I
2ce90 66 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 20 61 f.** the sixth a
2cea0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
2ceb0 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 e3_bind_text64()
2cec0 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 is not one of t
2ced0 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61 he.** allowed va
2cee0 6c 75 65 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 lues shown above
2cef0 2c 20 6f 72 20 69 66 20 74 68 65 20 74 65 78 74 , or if the text
2cf00 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 encoding is dif
2cf10 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 ferent.** from t
2cf20 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 he encoding spec
2cf30 69 66 69 65 64 20 62 79 20 74 68 65 20 73 69 78 ified by the six
2cf40 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 th parameter, th
2cf50 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a en the behavior.
2cf60 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e ** is undefined.
2cf70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
2cf80 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f te3_bind_zeroblo
2cf90 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 b() routine bind
2cfa0 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 s a BLOB of leng
2cfb0 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 th N that.** is
2cfc0 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f filled with zero
2cfd0 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 es. ^A zeroblob
2cfe0 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d uses a fixed am
2cff0 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a ount of memory.*
2d000 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 * (just an integ
2d010 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 er to hold its s
2d020 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 ize) while it is
2d030 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 being processed
2d040 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 ..** Zeroblobs a
2d050 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 re intended to s
2d060 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c erve as placehol
2d070 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 ders for BLOBs w
2d080 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 hose.** content
2d090 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e is later written
2d0a0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 using.** [sqlit
2d0b0 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 e3_blob_open | i
2d0c0 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 ncremental BLOB
2d0d0 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a I/O] routines..*
2d0e0 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 * ^A negative va
2d0f0 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f lue for the zero
2d100 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 blob results in
2d110 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c a zero-length BL
2d120 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e OB..**.** ^If an
2d130 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 y of the sqlite3
2d140 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e _bind_*() routin
2d150 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 es are called wi
2d160 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 th a NULL pointe
2d170 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 r.** for the [pr
2d180 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2d190 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 ] or with a prep
2d1a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 ared statement f
2d1b0 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c or which.** [sql
2d1c0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 ite3_step()] has
2d1d0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 been called mor
2d1e0 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 e recently than
2d1f0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
2d200 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 ],.** then the c
2d210 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 all will return
2d220 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e [SQLITE_MISUSE].
2d230 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 If any sqlite3
2d240 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 _bind_().** rout
2d250 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20 ine is passed a
2d260 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2d270 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 ent] that has be
2d280 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 en finalized, th
2d290 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 e.** result is u
2d2a0 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f ndefined and pro
2d2b0 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a bably harmful..*
2d2c0 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 *.** ^Bindings a
2d2d0 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 re not cleared b
2d2e0 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 y the [sqlite3_r
2d2f0 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e eset()] routine.
2d300 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 .** ^Unbound par
2d310 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 ameters are inte
2d320 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e rpreted as NULL.
2d330 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
2d340 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 te3_bind_* routi
2d350 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 nes return [SQLI
2d360 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 TE_OK] on succes
2d370 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f s or an.** [erro
2d380 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 r code] if anyth
2d390 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a ing goes wrong..
2d3a0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 ** ^[SQLITE_TOOB
2d3b0 49 47 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 IG] might be ret
2d3c0 75 72 6e 65 64 20 69 66 20 74 68 65 20 73 69 7a urned if the siz
2d3d0 65 20 6f 66 20 61 20 73 74 72 69 6e 67 20 6f 72 e of a string or
2d3e0 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 BLOB.** exceeds
2d3f0 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 limits imposed
2d400 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 by [sqlite3_limi
2d410 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 t]([SQLITE_LIMIT
2d420 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 _LENGTH]) or.**
2d430 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 [SQLITE_MAX_LENG
2d440 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 TH]..** ^[SQLITE
2d450 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 _RANGE] is retur
2d460 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d ned if the param
2d470 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 eter.** index is
2d480 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 out of range.
2d490 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 ^[SQLITE_NOMEM]
2d4a0 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d is returned if m
2d4b0 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a alloc() fails..*
2d4c0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
2d4d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
2d4e0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c ameter_count()],
2d4f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
2d500 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 d_parameter_name
2d510 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 ()], and [sqlite
2d520 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
2d530 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 _index()]..*/.SQ
2d540 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
2d550 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
2d560 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 te3_bind_blob(sq
2d570 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
2d580 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 , const void*, i
2d590 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f nt n, void(*)(vo
2d5a0 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 id*));.SQLITE_AP
2d5b0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
2d5c0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e CALL sqlite3_bin
2d5d0 64 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 d_blob64(sqlite3
2d5e0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e _stmt*, int, con
2d5f0 73 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 st void*, sqlite
2d600 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 3_uint64,.
2d610 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2d620 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 void(*)(void*)
2d630 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
2d640 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
2d650 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f sqlite3_bind_do
2d660 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d uble(sqlite3_stm
2d670 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 t*, int, double)
2d680 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
2d690 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
2d6a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 sqlite3_bind_int
2d6b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
2d6c0 69 6e 74 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 int, int);.SQLIT
2d6d0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
2d6e0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
2d6f0 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 _bind_int64(sqli
2d700 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
2d710 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a sqlite3_int64);.
2d720 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
2d730 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
2d740 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 lite3_bind_null(
2d750 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
2d760 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 nt);.SQLITE_API
2d770 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 int SQLITE_STDCA
2d780 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f LL sqlite3_bind_
2d790 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d text(sqlite3_stm
2d7a0 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 t*,int,const cha
2d7b0 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 r*,int,void(*)(v
2d7c0 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 oid*));.SQLITE_A
2d7d0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 PI int SQLITE_ST
2d7e0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 DCALL sqlite3_bi
2d7f0 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 nd_text16(sqlite
2d800 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 3_stmt*, int, co
2d810 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 nst void*, int,
2d820 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b void(*)(void*));
2d830 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
2d840 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
2d850 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
2d860 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 64(sqlite3_stmt*
2d870 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 , int, const cha
2d880 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 r*, sqlite3_uint
2d890 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 64,.
2d8a0 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 voi
2d8b0 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 d(*)(void*), uns
2d8c0 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f 64 igned char encod
2d8d0 69 6e 67 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ing);.SQLITE_API
2d8e0 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
2d8f0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 ALL sqlite3_bind
2d900 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 _value(sqlite3_s
2d910 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 tmt*, int, const
2d920 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 sqlite3_value*)
2d930 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
2d940 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
2d950 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 sqlite3_bind_zer
2d960 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 oblob(sqlite3_st
2d970 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 mt*, int, int n)
2d980 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
2d990 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
2d9a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 sqlite3_bind_zer
2d9b0 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f oblob64(sqlite3_
2d9c0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 stmt*, int, sqli
2d9d0 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a te3_uint64);../*
2d9e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 .** CAPI3REF: Nu
2d9f0 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 mber Of SQL Para
2da00 6d 65 74 65 72 73 0a 2a 2a 20 4d 45 54 48 4f 44 meters.** METHOD
2da10 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a : sqlite3_stmt.*
2da20 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 *.** ^This routi
2da30 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 ne can be used t
2da40 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 o find the numbe
2da50 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 r of [SQL parame
2da60 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 ters].** in a [p
2da70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2da80 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 t]. SQL paramet
2da90 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f ers are tokens o
2daa0 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f f the.** form "?
2dab0 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 ", "?NNN", ":AAA
2dac0 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 ", "$AAA", or "@
2dad0 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20 AAA" that serve
2dae0 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 as.** placeholde
2daf0 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 rs for values th
2db00 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f at are [sqlite3_
2db10 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e bind_blob | boun
2db20 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 d].** to the par
2db30 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 ameters at a lat
2db40 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e er time..**.** ^
2db50 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 (This routine ac
2db60 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 tually returns t
2db70 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 he index of the
2db80 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f largest (rightmo
2db90 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 st).** parameter
2dba0 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 . For all forms
2dbb0 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 except ?NNN, thi
2dbc0 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e s will correspon
2dbd0 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 d to the.** numb
2dbe0 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 er of unique par
2dbf0 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 ameters. If par
2dc00 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f ameters of the ?
2dc10 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 NNN form are use
2dc20 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 d,.** there may
2dc30 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c be gaps in the l
2dc40 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 ist.)^.**.** See
2dc50 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f also: [sqlite3_
2dc60 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 bind_blob|sqlite
2dc70 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 3_bind()],.** [s
2dc80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
2dc90 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 meter_name()], a
2dca0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 nd.** [sqlite3_b
2dcb0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e ind_parameter_in
2dcc0 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 dex()]..*/.SQLIT
2dcd0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
2dce0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
2dcf0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
2dd00 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 count(sqlite3_st
2dd10 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 mt*);../*.** CAP
2dd20 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 I3REF: Name Of A
2dd30 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a Host Parameter.
2dd40 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
2dd50 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 e3_stmt.**.** ^T
2dd60 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
2dd70 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 parameter_name(P
2dd80 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 ,N) interface re
2dd90 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d turns.** the nam
2dda0 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 e of the N-th [S
2ddb0 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e QL parameter] in
2ddc0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
2ddd0 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 tatement] P..**
2dde0 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 ^(SQL parameters
2ddf0 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e of the form "?N
2de00 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 NN" or ":AAA" or
2de10 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 "@AAA" or "$AAA
2de20 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 ".** have a name
2de30 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74 which is the st
2de40 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 ring "?NNN" or "
2de50 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 :AAA" or "@AAA"
2de60 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 or "$AAA".** res
2de70 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e pectively..** In
2de80 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 other words, th
2de90 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 e initial ":" or
2dea0 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 "$" or "@" or "
2deb0 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 ?".** is include
2dec0 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 d as part of the
2ded0 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 name.)^.** ^Par
2dee0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 ameters of the f
2def0 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 orm "?" without
2df00 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 a following inte
2df10 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 ger have no name
2df20 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 .** and are refe
2df30 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 rred to as "name
2df40 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d less" or "anonym
2df50 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e ous parameters".
2df60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 .**.** ^The firs
2df70 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 t host parameter
2df80 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 has an index of
2df90 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 1, not 0..**.**
2dfa0 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e ^If the value N
2dfb0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 is out of range
2dfc0 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 or if the N-th
2dfd0 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 parameter is.**
2dfe0 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e nameless, then N
2dff0 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e ULL is returned.
2e000 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 ^The returned
2e010 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 string is.** alw
2e020 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 ays in UTF-8 enc
2e030 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 oding even if th
2e040 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 e named paramete
2e050 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 r was.** origina
2e060 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73 lly specified as
2e070 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 UTF-16 in [sqli
2e080 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d te3_prepare16()]
2e090 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f or.** [sqlite3_
2e0a0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e prepare16_v2()].
2e0b0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
2e0c0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 [sqlite3_bind_b
2e0d0 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 lob|sqlite3_bind
2e0e0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
2e0f0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
2e100 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a count()], and.**
2e110 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
2e120 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 arameter_index()
2e130 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 ]..*/.SQLITE_API
2e140 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c const char *SQL
2e150 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
2e160 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
2e170 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f er_name(sqlite3_
2e180 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a stmt*, int);../*
2e190 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e .** CAPI3REF: In
2e1a0 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 dex Of A Paramet
2e1b0 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 er With A Given
2e1c0 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 Name.** METHOD:
2e1d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a sqlite3_stmt.**.
2e1e0 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 ** ^Return the i
2e1f0 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 ndex of an SQL p
2e200 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 arameter given i
2e210 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a ts name. ^The.*
2e220 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 * index value re
2e230 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 turned is suitab
2e240 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 le for use as th
2e250 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 e second.** para
2e260 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 meter to [sqlite
2e270 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 3_bind_blob|sqli
2e280 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 te3_bind()]. ^A
2e290 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 zero.** is retu
2e2a0 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 rned if no match
2e2b0 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 ing parameter is
2e2c0 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 found. ^The pa
2e2d0 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 rameter.** name
2e2e0 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e must be given in
2e2f0 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 UTF-8 even if t
2e300 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 he original stat
2e310 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 ement.** was pre
2e320 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 pared from UTF-1
2e330 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6 text using [sq
2e340 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
2e350 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 v2()]..**.** See
2e360 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f also: [sqlite3_
2e370 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 bind_blob|sqlite
2e380 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 3_bind()],.** [s
2e390 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
2e3a0 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 meter_count()],
2e3b0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f and.** [sqlite3_
2e3c0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e bind_parameter_n
2e3d0 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 ame()]..*/.SQLIT
2e3e0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
2e3f0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
2e400 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
2e410 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 index(sqlite3_st
2e420 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 mt*, const char
2e430 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 *zName);../*.**
2e440 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 CAPI3REF: Reset
2e450 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 All Bindings On
2e460 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 A Prepared State
2e470 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 ment.** METHOD:
2e480 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a sqlite3_stmt.**.
2e490 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 ** ^Contrary to
2e4a0 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 the intuition of
2e4b0 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f many, [sqlite3_
2e4c0 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f reset()] does no
2e4d0 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b t reset.** the [
2e4e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
2e4f0 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e b | bindings] on
2e500 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
2e510 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 tement]..** ^Use
2e520 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f this routine to
2e530 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 reset all host
2e540 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 parameters to NU
2e550 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 LL..*/.SQLITE_AP
2e560 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
2e570 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6c 65 CALL sqlite3_cle
2e580 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 ar_bindings(sqli
2e590 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a te3_stmt*);../*.
2e5a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d ** CAPI3REF: Num
2e5b0 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 ber Of Columns I
2e5c0 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a n A Result Set.*
2e5d0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
2e5e0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 3_stmt.**.** ^Re
2e5f0 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 turn the number
2e600 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 of columns in th
2e610 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 e result set ret
2e620 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 urned by the.**
2e630 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2e640 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 ent]. ^This rout
2e650 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 ine returns 0 if
2e660 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c pStmt is an SQL
2e670 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 .** statement th
2e680 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 at does not retu
2e690 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 rn data (for exa
2e6a0 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d mple an [UPDATE]
2e6b0 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 )..**.** See als
2e6c0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 o: [sqlite3_data
2e6d0 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c _count()].*/.SQL
2e6e0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 ITE_API int SQLI
2e6f0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
2e700 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 e3_column_count(
2e710 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 sqlite3_stmt *pS
2e720 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 tmt);../*.** CAP
2e730 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 I3REF: Column Na
2e740 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 mes In A Result
2e750 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 Set.** METHOD: s
2e760 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a qlite3_stmt.**.*
2e770 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 * ^These routine
2e780 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d s return the nam
2e790 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 e assigned to a
2e7a0 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d particular colum
2e7b0 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 n.** in the resu
2e7c0 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c lt set of a [SEL
2e7d0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 ECT] statement.
2e7e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f ^The sqlite3_co
2e7f0 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 lumn_name().** i
2e800 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
2e810 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
2e820 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
2e830 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 UTF-8 string.**
2e840 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 and sqlite3_colu
2e850 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 mn_name16() retu
2e860 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
2e870 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 a zero-terminat
2e880 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 ed.** UTF-16 str
2e890 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 ing. ^The first
2e8a0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
2e8b0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
2e8c0 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 ement].** that i
2e8d0 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 mplements the [S
2e8e0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 ELECT] statement
2e8f0 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 . ^The second pa
2e900 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a rameter is the.*
2e910 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e * column number.
2e920 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 ^The leftmost
2e930 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 column is number
2e940 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 0..**.** ^The r
2e950 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 eturned string p
2e960 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 ointer is valid
2e970 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 until either the
2e980 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2e990 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 ment].** is dest
2e9a0 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 royed by [sqlite
2e9b0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 3_finalize()] or
2e9c0 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 until the state
2e9d0 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 ment is automati
2e9e0 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 cally.** reprepa
2e9f0 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 red by the first
2ea00 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
2ea10 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 3_step()] for a
2ea20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a particular run.*
2ea30 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e * or until the n
2ea40 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 ext call to.** s
2ea50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 qlite3_column_na
2ea60 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f me() or sqlite3_
2ea70 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 column_name16()
2ea80 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 on the same colu
2ea90 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 mn..**.** ^If sq
2eaa0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 lite3_malloc() f
2eab0 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 ails during the
2eac0 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 processing of ei
2ead0 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 ther routine.**
2eae0 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 (for example dur
2eaf0 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e ing a conversion
2eb00 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 from UTF-8 to U
2eb10 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a TF-16) then a.**
2eb20 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 NULL pointer is
2eb30 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
2eb40 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 ^The name of a
2eb50 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 result column is
2eb60 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 the value of th
2eb70 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f e "AS" clause fo
2eb80 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e r.** that column
2eb90 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e , if there is an
2eba0 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 AS clause. If
2ebb0 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 there is no AS c
2ebc0 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 lause.** then th
2ebd0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f e name of the co
2ebe0 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 lumn is unspecif
2ebf0 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e ied and may chan
2ec00 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 ge from.** one r
2ec10 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 elease of SQLite
2ec20 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f to the next..*/
2ec30 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
2ec40 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 t char *SQLITE_S
2ec50 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 TDCALL sqlite3_c
2ec60 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 olumn_name(sqlit
2ec70 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 e3_stmt*, int N)
2ec80 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e ;.SQLITE_API con
2ec90 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f st void *SQLITE_
2eca0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
2ecb0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 column_name16(sq
2ecc0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
2ecd0 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 N);../*.** CAPI
2ece0 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 3REF: Source Of
2ecf0 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 Data In A Query
2ed00 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 Result.** METHOD
2ed10 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a : sqlite3_stmt.*
2ed20 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 *.** ^These rout
2ed30 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d ines provide a m
2ed40 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e eans to determin
2ed50 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 e the database,
2ed60 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 table, and.** ta
2ed70 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 ble column that
2ed80 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 is the origin of
2ed90 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 a particular re
2eda0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a sult column in.*
2edb0 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 * [SELECT] state
2edc0 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 ment..** ^The na
2edd0 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 me of the databa
2ede0 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 se or table or c
2edf0 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 olumn can be ret
2ee00 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 urned as.** eith
2ee10 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 er a UTF-8 or UT
2ee20 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 F-16 string. ^T
2ee30 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f he _database_ ro
2ee40 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a utines return.**
2ee50 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 the database na
2ee60 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 me, the _table_
2ee70 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
2ee80 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 the table name,
2ee90 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 and.** the origi
2eea0 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 n_ routines retu
2eeb0 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 rn the column na
2eec0 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 me..** ^The retu
2eed0 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 rned string is v
2eee0 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b alid until the [
2eef0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2ef00 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 nt] is destroyed
2ef10 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 .** using [sqlit
2ef20 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f e3_finalize()] o
2ef30 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 r until the stat
2ef40 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 ement is automat
2ef50 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 ically.** reprep
2ef60 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 ared by the firs
2ef70 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 t call to [sqlit
2ef80 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 e3_step()] for a
2ef90 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a particular run.
2efa0 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 ** or until the
2efb0 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e same information
2efc0 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a is requested.**
2efd0 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 again in a diff
2efe0 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a erent encoding..
2eff0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 **.** ^The names
2f000 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 returned are th
2f010 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c e original un-al
2f020 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 iased names of t
2f030 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 he.** database,
2f040 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d table, and colum
2f050 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 n..**.** ^The fi
2f060 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rst argument to
2f070 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 these interfaces
2f080 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 is a [prepared
2f090 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e statement]..** ^
2f0a0 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 These functions
2f0b0 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 return informati
2f0c0 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 on about the Nth
2f0d0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 result column r
2f0e0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 eturned by.** th
2f0f0 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 e statement, whe
2f100 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f re N is the seco
2f110 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 nd function argu
2f120 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 ment..** ^The le
2f130 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 ft-most column i
2f140 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 s column 0 for t
2f150 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a hese routines..*
2f160 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 *.** ^If the Nth
2f170 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 column returned
2f180 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e by the statemen
2f190 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 t is an expressi
2f1a0 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 on or.** subquer
2f1b0 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 y and is not a c
2f1c0 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 olumn value, the
2f1d0 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 n all of these f
2f1e0 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a unctions return.
2f1f0 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 ** NULL. ^These
2f200 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 routine might a
2f210 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 lso return NULL
2f220 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f if a memory allo
2f230 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 cation error.**
2f240 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 occurs. ^Otherw
2f250 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e ise, they return
2f260 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
2f270 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 attached databa
2f280 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 se, table,.** or
2f290 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 column that que
2f2a0 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e ry result column
2f2b0 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66 was extracted f
2f2c0 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 rom..**.** ^As w
2f2d0 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 ith all other SQ
2f2e0 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 Lite APIs, those
2f2f0 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 whose names end
2f300 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72 with "16" retur
2f310 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f n.** UTF-16 enco
2f320 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 ded strings and
2f330 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 the other functi
2f340 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 ons return UTF-8
2f350 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 ..**.** ^These A
2f360 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 PIs are only ava
2f370 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 ilable if the li
2f380 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c brary was compil
2f390 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b ed with the.** [
2f3a0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f SQLITE_ENABLE_CO
2f3b0 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 LUMN_METADATA] C
2f3c0 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 -preprocessor sy
2f3d0 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 mbol..**.** If t
2f3e0 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 wo or more threa
2f3f0 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d ds call one or m
2f400 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 ore of these rou
2f410 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 tines against th
2f420 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 e same.** prepar
2f430 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 ed statement and
2f440 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 column at the s
2f450 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 ame time then th
2f460 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a e results are.**
2f470 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a undefined..**.*
2f480 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 * If two or more
2f490 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e threads call on
2f4a0 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 e or more.** [sq
2f4b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 lite3_column_dat
2f4c0 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c abase_name | col
2f4d0 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 umn metadata int
2f4e0 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 erfaces].** for
2f4f0 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 the same [prepar
2f500 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e ed statement] an
2f510 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a d result column.
2f520 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 ** at the same t
2f530 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 ime then the res
2f540 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e ults are undefin
2f550 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 ed..*/.SQLITE_AP
2f560 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 I const char *SQ
2f570 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
2f580 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 ite3_column_data
2f590 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 base_name(sqlite
2f5a0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 3_stmt*,int);.SQ
2f5b0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 LITE_API const v
2f5c0 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 oid *SQLITE_STDC
2f5d0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ALL sqlite3_colu
2f5e0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 mn_database_name
2f5f0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
2f600 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 ,int);.SQLITE_AP
2f610 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 I const char *SQ
2f620 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
2f630 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c ite3_column_tabl
2f640 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 e_name(sqlite3_s
2f650 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 tmt*,int);.SQLIT
2f660 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 E_API const void
2f670 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c *SQLITE_STDCALL
2f680 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2f690 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c table_name16(sql
2f6a0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b ite3_stmt*,int);
2f6b0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
2f6c0 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 t char *SQLITE_S
2f6d0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 TDCALL sqlite3_c
2f6e0 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d olumn_origin_nam
2f6f0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
2f700 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 int);.SQLITE_API
2f710 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c const void *SQL
2f720 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
2f730 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 te3_column_origi
2f740 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 n_name16(sqlite3
2f750 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a _stmt*,int);../*
2f760 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 .** CAPI3REF: De
2f770 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20 clared Datatype
2f780 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c Of A Query Resul
2f790 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c t.** METHOD: sql
2f7a0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 ite3_stmt.**.**
2f7b0 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61 ^(The first para
2f7c0 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 meter is a [prep
2f7d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e ared statement].
2f7e0 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 .** If this stat
2f7f0 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 ement is a [SELE
2f800 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e CT] statement an
2f810 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e d the Nth column
2f820 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 of the.** retur
2f830 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f ned result set o
2f840 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 f that [SELECT]
2f850 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d is a table colum
2f860 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 n (not an.** exp
2f870 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 ression or subqu
2f880 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 ery) then the de
2f890 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 clared type of t
2f8a0 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 he table.** colu
2f8b0 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 mn is returned.)
2f8c0 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 ^ ^If the Nth c
2f8d0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 olumn of the res
2f8e0 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a ult set is an.**
2f8f0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 expression or s
2f900 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 ubquery, then a
2f910 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 NULL pointer is
2f920 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 returned..** ^Th
2f930 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e e returned strin
2f940 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d g is always UTF-
2f950 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 8 encoded..**.**
2f960 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 ^(For example,
2f970 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 given the databa
2f980 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a se schema:.**.**
2f990 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 CREATE TABLE t1
2f9a0 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a (c1 VARIANT);.**
2f9b0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c .** and the foll
2f9c0 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 owing statement
2f9d0 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a to be compiled:.
2f9e0 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 **.** SELECT c1
2f9f0 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b + 1, c1 FROM t1;
2fa00 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 .**.** this rout
2fa10 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e ine would return
2fa20 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 the string "VAR
2fa30 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 IANT" for the se
2fa40 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 cond result.** c
2fa50 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e olumn (i==1), an
2fa60 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 d a NULL pointer
2fa70 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 for the first r
2fa80 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d esult column (i=
2fa90 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 =0).)^.**.** ^SQ
2faa0 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 Lite uses dynami
2fab0 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e c run-time typin
2fac0 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 g. ^So just bec
2fad0 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a ause a column.**
2fae0 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 is declared to
2faf0 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 contain a partic
2fb00 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e ular type does n
2fb10 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 ot mean that the
2fb20 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 .** data stored
2fb30 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 in that column i
2fb40 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 s of the declare
2fb50 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 d type. SQLite
2fb60 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 is.** strongly t
2fb70 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 yped, but the ty
2fb80 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 ping is dynamic
2fb90 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 not static. ^Ty
2fba0 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 pe.** is associa
2fbb0 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 ted with individ
2fbc0 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 ual values, not
2fbd0 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e with the contain
2fbe0 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 ers.** used to h
2fbf0 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 old those values
2fc00 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
2fc10 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 const char *SQLI
2fc20 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
2fc30 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 e3_column_declty
2fc40 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a pe(sqlite3_stmt*
2fc50 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 ,int);.SQLITE_AP
2fc60 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 I const void *SQ
2fc70 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
2fc80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c ite3_column_decl
2fc90 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 type16(sqlite3_s
2fca0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a tmt*,int);../*.*
2fcb0 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c * CAPI3REF: Eval
2fcc0 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 uate An SQL Stat
2fcd0 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a ement.** METHOD:
2fce0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a sqlite3_stmt.**
2fcf0 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 .** After a [pre
2fd00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2fd10 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 has been prepar
2fd20 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a ed using either.
2fd30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
2fd40 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 are_v2()] or [sq
2fd50 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
2fd60 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 v2()] or one of
2fd70 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e the legacy.** in
2fd80 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 terfaces [sqlite
2fd90 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 3_prepare()] or
2fda0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
2fdb0 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 16()], this func
2fdc0 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 tion.** must be
2fdd0 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f called one or mo
2fde0 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c re times to eval
2fdf0 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 uate the stateme
2fe00 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 nt..**.** The de
2fe10 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 tails of the beh
2fe20 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c avior of the sql
2fe30 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 ite3_step() inte
2fe40 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 rface depend.**
2fe50 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73 on whether the s
2fe60 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 tatement was pre
2fe70 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 pared using the
2fe80 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 newer "v2" inter
2fe90 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 face.** [sqlite3
2fea0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 _prepare_v2()] a
2feb0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 nd [sqlite3_prep
2fec0 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 are16_v2()] or t
2fed0 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a he older legacy.
2fee0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 ** interface [sq
2fef0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d lite3_prepare()]
2ff00 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 and [sqlite3_pr
2ff10 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 epare16()]. The
2ff20 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e use of the.** n
2ff30 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 ew "v2" interfac
2ff40 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 e is recommended
2ff50 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 for new applica
2ff60 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 tions but the le
2ff70 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 gacy.** interfac
2ff80 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 e will continue
2ff90 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e to be supported.
2ffa0 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c .**.** ^In the l
2ffb0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c egacy interface,
2ffc0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 the return valu
2ffd0 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 e will be either
2ffe0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a [SQLITE_BUSY],.
2fff0 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d ** [SQLITE_DONE]
30000 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 , [SQLITE_ROW],
30010 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 [SQLITE_ERROR],
30020 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 or [SQLITE_MISUS
30030 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 E]..** ^With the
30040 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c "v2" interface,
30050 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 any of the othe
30060 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d r [result codes]
30070 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 or.** [extended
30080 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d result codes] m
30090 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 ight be returned
300a0 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 as well..**.**
300b0 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d ^[SQLITE_BUSY] m
300c0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 eans that the da
300d0 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 tabase engine wa
300e0 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 s unable to acqu
300f0 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 ire the.** datab
30100 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 ase locks it nee
30110 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 ds to do its job
30120 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 . ^If the state
30130 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 ment is a [COMMI
30140 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 T].** or occurs
30150 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 outside of an ex
30160 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 plicit transacti
30170 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e on, then you can
30180 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 retry the.** st
30190 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 atement. If the
301a0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f statement is no
301b0 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 t a [COMMIT] and
301c0 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 occurs within a
301d0 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 n.** explicit tr
301e0 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 ansaction then y
301f0 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 ou should rollba
30200 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 ck the transacti
30210 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e on before.** con
30220 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e tinuing..**.** ^
30230 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 [SQLITE_DONE] me
30240 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61 ans that the sta
30250 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 tement has finis
30260 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a hed executing.**
30270 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 successfully.
30280 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 sqlite3_step() s
30290 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c hould not be cal
302a0 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 led again on thi
302b0 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 s virtual.** mac
302c0 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 hine without fir
302d0 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 st calling [sqli
302e0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 te3_reset()] to
302f0 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61 reset the virtua
30300 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 l.** machine bac
30310 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c k to its initial
30320 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 state..**.** ^I
30330 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d f the SQL statem
30340 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 ent being execut
30350 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 ed returns any d
30360 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 ata, then [SQLIT
30370 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 E_ROW].** is ret
30380 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 urned each time
30390 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 a new row of dat
303a0 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 a is ready for p
303b0 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 rocessing by the
303c0 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 .** caller. The
303d0 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 values may be ac
303e0 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 cessed using the
303f0 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 [column access
30400 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 functions]..** s
30410 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 qlite3_step() is
30420 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f called again to
30430 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 retrieve the ne
30440 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a xt row of data..
30450 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 **.** ^[SQLITE_E
30460 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 RROR] means that
30470 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f a run-time erro
30480 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e r (such as a con
30490 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 straint.** viola
304a0 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 tion) has occurr
304b0 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 ed. sqlite3_ste
304c0 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 p() should not b
304d0 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f e called again o
304e0 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 n.** the VM. Mor
304f0 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 e information ma
30500 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 y be found by ca
30510 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 lling [sqlite3_e
30520 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 rrmsg()]..** ^Wi
30530 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e th the legacy in
30540 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 terface, a more
30550 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 specific error c
30560 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 ode (for example
30570 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 ,.** [SQLITE_INT
30580 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 ERRUPT], [SQLITE
30590 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 _SCHEMA], [SQLIT
305a0 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 E_CORRUPT], and
305b0 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e so forth).** can
305c0 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 be obtained by
305d0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 calling [sqlite3
305e0 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 _reset()] on the
305f0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 .** [prepared st
30600 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 atement]. ^In t
30610 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 he "v2" interfac
30620 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 e,.** the more s
30630 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f pecific error co
30640 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 de is returned d
30650 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 irectly by sqlit
30660 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a e3_step()..**.**
30670 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d [SQLITE_MISUSE]
30680 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 means that the
30690 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 this routine was
306a0 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 called inapprop
306b0 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 riately..** Perh
306c0 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 aps it was calle
306d0 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 d on a [prepared
306e0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 statement] that
306f0 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 has.** already
30700 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 been [sqlite3_fi
30710 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a nalize | finaliz
30720 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 ed] or on one th
30730 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f at had.** previo
30740 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 usly returned [S
30750 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 QLITE_ERROR] or
30760 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 [SQLITE_DONE].
30770 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 Or it could.** b
30780 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 e the case that
30790 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 the same databas
307a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 e connection is
307b0 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 being used by tw
307c0 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 o or.** more thr
307d0 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 eads at the same
307e0 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e moment in time.
307f0 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 .**.** For all v
30800 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
30810 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c e up to and incl
30820 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 uding 3.6.23.1,
30830 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 a call to.** [sq
30840 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 lite3_reset()] w
30850 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74 65 as required afte
30860 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 r sqlite3_step()
30870 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 returned anythi
30880 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e ng.** other than
30890 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 [SQLITE_ROW] be
308a0 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 fore any subsequ
308b0 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f ent invocation o
308c0 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 f.** sqlite3_ste
308d0 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f p(). Failure to
308e0 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 reset the prepa
308f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 red statement us
30900 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ing .** [sqlite3
30910 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 _reset()] would
30920 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 result in an [SQ
30930 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 LITE_MISUSE] ret
30940 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 urn from.** sqli
30950 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 te3_step(). But
30960 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33 after version 3
30970 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 .6.23.1, sqlite3
30980 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a _step() began.**
30990 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 calling [sqlite
309a0 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 3_reset()] autom
309b0 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 atically in this
309c0 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 circumstance ra
309d0 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 ther.** than ret
309e0 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d urning [SQLITE_M
309f0 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 ISUSE]. This is
30a00 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 not considered
30a10 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a a compatibility.
30a20 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 ** break because
30a30 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e any application
30a40 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65 69 that ever recei
30a50 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 ves an SQLITE_MI
30a60 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 SUSE error.** is
30a70 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e broken by defin
30a80 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c ition. The [SQL
30a90 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 ITE_OMIT_AUTORES
30aa0 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 ET] compile-time
30ab0 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 option.** can b
30ac0 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 e used to restor
30ad0 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 e the legacy beh
30ae0 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e avior..**.** <b>
30af0 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 Goofy Interface
30b00 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 Alert:</b> In th
30b10 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 e legacy interfa
30b20 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f ce, the sqlite3_
30b30 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c step().** API al
30b40 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 ways returns a g
30b50 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 eneric error cod
30b60 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 e, [SQLITE_ERROR
30b70 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 ], following any
30b80 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 .** error other
30b90 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 than [SQLITE_BUS
30ba0 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d Y] and [SQLITE_M
30bb0 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 ISUSE]. You mus
30bc0 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 t call.** [sqlit
30bd0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b e3_reset()] or [
30be0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
30bf0 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 ()] in order to
30c00 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a find one of the.
30c10 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 ** specific [err
30c20 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 or codes] that b
30c30 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20 etter describes
30c40 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 the error..** We
30c50 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 admit that this
30c60 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 is a goofy desi
30c70 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d gn. The problem
30c80 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a has been fixed.
30c90 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22 ** with the "v2"
30ca0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 interface. If
30cb0 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 you prepare all
30cc0 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 of your SQL stat
30cd0 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 ements.** using
30ce0 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f either [sqlite3_
30cf0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 prepare_v2()] or
30d00 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
30d10 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 e16_v2()] instea
30d20 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 d.** of the lega
30d30 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 cy [sqlite3_prep
30d40 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 are()] and [sqli
30d50 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d te3_prepare16()]
30d60 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 interfaces,.**
30d70 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 then the more sp
30d80 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f ecific [error co
30d90 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 des] are returne
30da0 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 d directly.** by
30db0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e sqlite3_step().
30dc0 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 The use of the
30dd0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 "v2" interface
30de0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a is recommended..
30df0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
30e00 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
30e10 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 sqlite3_step(sq
30e20 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f lite3_stmt*);../
30e30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e *.** CAPI3REF: N
30e40 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
30e50 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 in a result set
30e60 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
30e70 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e te3_stmt.**.** ^
30e80 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 The sqlite3_data
30e90 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 _count(P) interf
30ea0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ace returns the
30eb0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e number of column
30ec0 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 s in the.** curr
30ed0 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 ent row of the r
30ee0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 esult set of [pr
30ef0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
30f00 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 ] P..** ^If prep
30f10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 ared statement P
30f20 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 does not have r
30f30 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 esults ready to
30f40 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 return.** (via c
30f50 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c alls to the [sql
30f60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 ite3_column_int
30f70 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e | sqlite3_column
30f80 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 _*()] of.** inte
30f90 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c rfaces) then sql
30fa0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 ite3_data_count(
30fb0 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a P) returns 0..**
30fc0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 ^The sqlite3_da
30fd0 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 ta_count(P) rout
30fe0 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 ine also returns
30ff0 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 0 if P is a NUL
31000 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 L pointer..** ^T
31010 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f he sqlite3_data_
31020 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 count(P) routine
31030 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 68 returns 0 if th
31040 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 e previous call
31050 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 to.** [sqlite3_s
31060 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 tep](P) returned
31070 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 [SQLITE_DONE].
31080 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 ^The sqlite3_da
31090 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 ta_count(P).** w
310a0 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a ill return non-z
310b0 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20 ero if previous
310c0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
310d0 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e _step](P) return
310e0 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f ed.** [SQLITE_RO
310f0 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68 W], except in th
31100 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50 e case of the [P
31110 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 RAGMA incrementa
31120 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 l_vacuum].** whe
31130 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 re it always ret
31140 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 urns zero since
31150 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 61 each step of tha
31160 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 t multi-step.**
31170 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30 pragma returns 0
31180 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 columns of data
31190 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
311a0 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d : [sqlite3_colum
311b0 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 n_count()].*/.SQ
311c0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
311d0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
311e0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 te3_data_count(s
311f0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
31200 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 mt);../*.** CAPI
31210 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 3REF: Fundamenta
31220 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b l Datatypes.** K
31230 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f EYWORDS: SQLITE_
31240 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 TEXT.**.** ^(Eve
31250 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 ry value in SQLi
31260 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 te has one of fi
31270 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 ve fundamental d
31280 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 atatypes:.**.**
31290 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d <ul>.** <li> 64-
312a0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 bit signed integ
312b0 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 er.** <li> 64-bi
312c0 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 t IEEE floating
312d0 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 point number.**
312e0 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c <li> string.** <
312f0 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e li> BLOB.** <li>
31300 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e NULL.** </ul>)^
31310 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e .**.** These con
31320 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 stants are codes
31330 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f for each of tho
31340 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 se types..**.**
31350 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51 Note that the SQ
31360 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 LITE_TEXT consta
31370 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 nt was also used
31380 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 in SQLite versi
31390 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f on 2.** for a co
313a0 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 mpletely differe
313b0 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 nt meaning. Sof
313c0 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 tware that links
313d0 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a against both.**
313e0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
313f0 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 2 and SQLite ver
31400 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 sion 3 should us
31410 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 e SQLITE3_TEXT,
31420 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 not.** SQLITE_TE
31430 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 XT..*/.#define S
31440 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 QLITE_INTEGER 1
31450 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
31460 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 FLOAT 2.#defi
31470 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 ne SQLITE_BLOB
31480 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 4.#define SQL
31490 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 ITE_NULL 5.#
314a0 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 ifdef SQLITE_TEX
314b0 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 T.# undef SQLITE
314c0 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 _TEXT.#else.# de
314d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 fine SQLITE_TEXT
314e0 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 3.#endif.#d
314f0 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 efine SQLITE3_TE
31500 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 XT 3../*.**
31510 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 CAPI3REF: Result
31520 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 Values From A Q
31530 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 uery.** KEYWORDS
31540 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 : {column access
31550 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d functions}.** M
31560 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 ETHOD: sqlite3_s
31570 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 tmt.**.** ^These
31580 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
31590 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f information abo
315a0 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 ut a single colu
315b0 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e mn of the curren
315c0 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 t.** result row
315d0 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e of a query. ^In
315e0 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20 every case the
315f0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 first argument i
31600 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 s a pointer.** t
31610 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 o the [prepared
31620 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 statement] that
31630 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 is being evaluat
31640 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 ed (the [sqlite3
31650 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 _stmt*].** that
31660 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f was returned fro
31670 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 m [sqlite3_prepa
31680 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 re_v2()] or one
31690 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 of its variants)
316a0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f .** and the seco
316b0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 nd argument is t
316c0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 he index of the
316d0 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 column for which
316e0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 information.**
316f0 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e should be return
31700 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 ed. ^The leftmos
31710 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 t column of the
31720 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 result set has t
31730 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e he index 0..** ^
31740 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f The number of co
31750 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 lumns in the res
31760 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 ult can be deter
31770 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b mined using.** [
31780 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 sqlite3_column_c
31790 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 ount()]..**.** I
317a0 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d f the SQL statem
317b0 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 ent does not cur
317c0 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 rently point to
317d0 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 a valid row, or
317e0 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e if the.** column
317f0 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 index is out of
31800 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 range, the resu
31810 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e lt is undefined.
31820 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
31830 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 es may only be c
31840 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d alled when the m
31850 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 ost recent call
31860 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 to.** [sqlite3_s
31870 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 tep()] has retur
31880 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d ned [SQLITE_ROW]
31890 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 and neither.**
318a0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
318b0 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 ] nor [sqlite3_f
318c0 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 inalize()] have
318d0 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 been called subs
318e0 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 equently..** If
318f0 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 any of these rou
31900 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 tines are called
31910 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f after [sqlite3_
31920 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b reset()] or.** [
31930 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
31940 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 ()] or after [sq
31950 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 lite3_step()] ha
31960 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f s returned.** so
31970 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 mething other th
31980 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c an [SQLITE_ROW],
31990 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 the results are
319a0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 undefined..** I
319b0 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 f [sqlite3_step(
319c0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 )] or [sqlite3_r
319d0 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 eset()] or [sqli
319e0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a te3_finalize()].
319f0 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 ** are called fr
31a00 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 om a different t
31a10 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 hread while any
31a20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 of these routine
31a30 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 s.** are pending
31a40 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c , then the resul
31a50 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 ts are undefined
31a60 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
31a70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 ite3_column_type
31a80 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 () routine retur
31a90 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 ns the.** [SQLIT
31aa0 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 E_INTEGER | data
31ab0 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 type code] for t
31ac0 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 he initial data
31ad0 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 type.** of the r
31ae0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e esult column. ^
31af0 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c The returned val
31b00 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 ue is one of [SQ
31b10 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a LITE_INTEGER],.*
31b20 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d * [SQLITE_FLOAT]
31b30 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c , [SQLITE_TEXT],
31b40 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 [SQLITE_BLOB],
31b50 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d or [SQLITE_NULL]
31b60 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 . The value.**
31b70 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 returned by sqli
31b80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 te3_column_type(
31b90 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e ) is only meanin
31ba0 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a gful if no type.
31bb0 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 ** conversions h
31bc0 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 ave occurred as
31bd0 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e described below.
31be0 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 After a type c
31bf0 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 onversion,.** th
31c00 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
31c10 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 by sqlite3_colu
31c20 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 mn_type() is und
31c30 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a efined. Future.
31c40 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 ** versions of S
31c50 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 QLite may change
31c60 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 the behavior of
31c70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
31c80 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 type().** follow
31c90 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 ing a type conve
31ca0 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 rsion..**.** ^If
31cb0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 the result is a
31cc0 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 BLOB or UTF-8 s
31cd0 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 tring then the s
31ce0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
31cf0 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 tes().** routine
31d00 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
31d10 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 ber of bytes in
31d20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 that BLOB or str
31d30 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ing..** ^If the
31d40 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d result is a UTF-
31d50 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 16 string, then
31d60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
31d70 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a ytes() converts.
31d80 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f ** the string to
31d90 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 UTF-8 and then
31da0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 returns the numb
31db0 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 er of bytes..**
31dc0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 ^If the result i
31dd0 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 s a numeric valu
31de0 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 e then sqlite3_c
31df0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 olumn_bytes() us
31e00 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 es.** [sqlite3_s
31e10 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f nprintf()] to co
31e20 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 nvert that value
31e30 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 to a UTF-8 stri
31e40 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a ng and returns.*
31e50 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 * the number of
31e60 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 bytes in that st
31e70 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 ring..** ^If the
31e80 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c result is NULL,
31e90 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f then sqlite3_co
31ea0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 lumn_bytes() ret
31eb0 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a urns zero..**.**
31ec0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 ^If the result
31ed0 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 is a BLOB or UTF
31ee0 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 -16 string then
31ef0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 the sqlite3_colu
31f00 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 mn_bytes16().**
31f10 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
31f20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
31f30 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 tes in that BLOB
31f40 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e or string..** ^
31f50 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 If the result is
31f60 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c a UTF-8 string,
31f70 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f then sqlite3_co
31f80 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 lumn_bytes16() c
31f90 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 onverts.** the s
31fa0 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 tring to UTF-16
31fb0 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 and then returns
31fc0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
31fd0 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 ytes..** ^If the
31fe0 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d result is a num
31ff0 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 eric value then
32000 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
32010 79 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a ytes16() uses.**
32020 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e [sqlite3_snprin
32030 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 tf()] to convert
32040 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 that value to a
32050 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 UTF-16 string a
32060 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 nd returns.** th
32070 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
32080 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 s in that string
32090 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 ..** ^If the res
320a0 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 ult is NULL, the
320b0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e n sqlite3_column
320c0 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72 _bytes16() retur
320d0 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e ns zero..**.** ^
320e0 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 The values retur
320f0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f ned by [sqlite3_
32100 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 column_bytes()]
32110 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and .** [sqlite3
32120 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
32130 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 )] do not includ
32140 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 e the zero termi
32150 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e nators at the en
32160 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 d.** of the stri
32170 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 ng. ^For clarit
32180 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 y: the values re
32190 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 turned by.** [sq
321a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
321b0 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 es()] and [sqlit
321c0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
321d0 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 6()] are the num
321e0 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 ber of.** bytes
321f0 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e in the string, n
32200 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ot the number of
32210 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a characters..**.
32220 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 ** ^Strings retu
32230 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f rned by sqlite3_
32240 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e column_text() an
32250 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e d sqlite3_column
32260 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 _text16(),.** ev
32270 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 en empty strings
32280 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 , are always zer
32290 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e o-terminated. ^
322a0 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 The return.** va
322b0 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 lue from sqlite3
322c0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 _column_blob() f
322d0 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 or a zero-length
322e0 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 BLOB is a NULL
322f0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c pointer..**.** <
32300 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e b>Warning:</b> ^
32310 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 The object retur
32320 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f ned by [sqlite3_
32330 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 column_value()]
32340 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 is an.** [unprot
32350 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
32360 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e lue] object. In
32370 20 61 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 a multithreaded
32380 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a environment,.**
32390 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 an unprotected
323a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
323b0 6a 65 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 ject may only be
323c0 20 75 73 65 64 20 73 61 66 65 6c 79 20 77 69 74 used safely wit
323d0 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 h.** [sqlite3_bi
323e0 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 nd_value()] and
323f0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f [sqlite3_result_
32400 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 value()]..** If
32410 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 the [unprotected
32420 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
32430 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 object returned
32440 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 by.** [sqlite3_c
32450 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 olumn_value()] i
32460 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 s used in any ot
32470 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 her way, includi
32480 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 ng calls.** to r
32490 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 outines like [sq
324a0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 lite3_value_int(
324b0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c )], [sqlite3_val
324c0 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f ue_text()],.** o
324d0 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 r [sqlite3_value
324e0 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 20 62 _bytes()], the b
324f0 65 68 61 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 ehavior is not t
32500 68 72 65 61 64 73 61 66 65 2e 0a 2a 2a 0a 2a 2a hreadsafe..**.**
32510 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
32520 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 attempt to conve
32530 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 rt the value whe
32540 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 re appropriate.
32550 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 ^For.** example
32560 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 , if the interna
32570 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e l representation
32580 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 is FLOAT and a
32590 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 text result.** i
325a0 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 s requested, [sq
325b0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 lite3_snprintf()
325c0 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e ] is used intern
325d0 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 ally to perform
325e0 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f the.** conversio
325f0 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e n automatically.
32600 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e ^(The followin
32610 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 g table details
32620 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a the conversions.
32630 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c ** that are appl
32640 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 ied:.**.** <bloc
32650 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c kquote>.** <tabl
32660 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a e border="1">.**
32670 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e <tr><th> Intern
32680 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 al<br>Type <th>
32690 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 Requested<br>Typ
326a0 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 e <th> Conversi
326b0 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 on.**.** <tr><td
326c0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 > NULL <td>
326d0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 INTEGER <td> R
326e0 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 esult is 0.** <t
326f0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 r><td> NULL
32700 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c <td> FLOAT <
32710 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e td> Result is 0.
32720 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 0.** <tr><td> N
32730 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 ULL <td> TE
32740 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c XT <td> Resul
32750 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e t is a NULL poin
32760 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 ter.** <tr><td>
32770 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 NULL <td>
32780 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 BLOB <td> Res
32790 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f ult is a NULL po
327a0 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 inter.** <tr><td
327b0 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 > INTEGER <td>
327c0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 FLOAT <td> C
327d0 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 onvert from inte
327e0 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 ger to float.**
327f0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 <tr><td> INTEGER
32800 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 <td> TEXT
32810 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 <td> ASCII rend
32820 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 ering of the int
32830 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e eger.** <tr><td>
32840 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 INTEGER <td>
32850 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 BLOB <td> Sa
32860 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 me as INTEGER->T
32870 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 EXT.** <tr><td>
32880 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e FLOAT <td> IN
32890 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 TEGER <td> [CA
328a0 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a ST] to INTEGER.*
328b0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 * <tr><td> FLOA
328c0 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 T <td> TEXT
328d0 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 <td> ASCII re
328e0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 ndering of the f
328f0 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e loat.** <tr><td>
32900 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 FLOAT <td>
32910 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 BLOB <td> [C
32920 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 AST] to BLOB.**
32930 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 <tr><td> TEXT
32940 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 <td> INTEGER
32950 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 <td> [CAST] to
32960 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c INTEGER.** <tr><
32970 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 td> TEXT <td
32980 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e > FLOAT <td>
32990 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a [CAST] to REAL.
329a0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 ** <tr><td> TEX
329b0 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 T <td> BLOB
329c0 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e <td> No chan
329d0 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 ge.** <tr><td>
329e0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 BLOB <td> INT
329f0 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 EGER <td> [CAS
32a00 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a T] to INTEGER.**
32a10 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 <tr><td> BLOB
32a20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 <td> FLOAT
32a30 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f <td> [CAST] to
32a40 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 REAL.** <tr><td
32a50 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 > BLOB <td>
32a60 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 TEXT <td> A
32a70 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e dd a zero termin
32a80 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a ator if needed.*
32a90 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f * </table>.** </
32aa0 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a blockquote>)^.**
32ab0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 .** Note that wh
32ac0 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 en type conversi
32ad0 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 ons occur, point
32ae0 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 ers returned by
32af0 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 prior.** calls t
32b00 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e o sqlite3_column
32b10 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 _blob(), sqlite3
32b20 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 _column_text(),
32b30 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 and/or.** sqlite
32b40 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
32b50 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 ) may be invalid
32b60 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f ated..** Type co
32b70 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f nversions and po
32b80 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 inter invalidati
32b90 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a ons might occur.
32ba0 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 ** in the follow
32bb0 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a ing cases:.**.**
32bc0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 <ul>.** <li> Th
32bd0 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e e initial conten
32be0 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 t is a BLOB and
32bf0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
32c00 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 ext() or.**
32c10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
32c20 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c text16() is call
32c30 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d ed. A zero-term
32c40 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 inator might.**
32c50 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 need to be
32c60 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 added to the str
32c70 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 ing.</li>.** <li
32c80 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f > The initial co
32c90 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 ntent is UTF-8 t
32ca0 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f ext and sqlite3_
32cb0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
32cc0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 or.** sqli
32cd0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
32ce0 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 6() is called.
32cf0 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 The content must
32d00 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a be converted.**
32d10 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e to UTF-16.
32d20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 </li>.** <li> Th
32d30 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e e initial conten
32d40 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 t is UTF-16 text
32d50 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c and sqlite3_col
32d60 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a umn_bytes() or.*
32d70 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 * sqlite3_c
32d80 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 olumn_text() is
32d90 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e called. The con
32da0 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e tent must be con
32db0 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 verted.** t
32dc0 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a o UTF-8.</li>.**
32dd0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f </ul>.**.** ^Co
32de0 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 nversions betwee
32df0 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 n UTF-16be and U
32e00 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 TF-16le are alwa
32e10 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 ys done in place
32e20 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 and do.** not i
32e30 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f nvalidate a prio
32e40 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 r pointer, thoug
32e50 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 h of course the
32e60 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 content of the b
32e70 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 uffer.** that th
32e80 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 e prior pointer
32e90 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 references will
32ea0 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 have been modifi
32eb0 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 ed. Other kinds
32ec0 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f .** of conversio
32ed0 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c n are done in pl
32ee0 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 ace when it is p
32ef0 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d ossible, but som
32f00 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 etimes they.** a
32f10 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 re not possible
32f20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 and in those cas
32f30 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 es prior pointer
32f40 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 s are invalidate
32f50 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 d..**.** The saf
32f60 65 73 74 20 70 6f 6c 69 63 79 20 69 73 20 74 6f est policy is to
32f70 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f invoke these ro
32f80 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 utines.** in one
32f90 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e of the followin
32fa0 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 g ways:.**.** <u
32fb0 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 l>.** <li>sqlit
32fc0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
32fd0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c followed by sql
32fe0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
32ff0 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 s()</li>.** <li
33000 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f >sqlite3_column_
33010 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 blob() followed
33020 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d by sqlite3_colum
33030 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a n_bytes()</li>.*
33040 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 * <li>sqlite3_c
33050 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 olumn_text16() f
33060 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 ollowed by sqlit
33070 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
33080 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 6()</li>.** </ul
33090 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 >.**.** In other
330a0 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 words, you shou
330b0 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f ld call sqlite3_
330c0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a column_text(),.*
330d0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e * sqlite3_column
330e0 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 _blob(), or sqli
330f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
33100 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 6() first to for
33110 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a ce the result.**
33120 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 into the desire
33130 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 d format, then i
33140 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f nvoke sqlite3_co
33150 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a lumn_bytes() or.
33160 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d ** sqlite3_colum
33170 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 n_bytes16() to f
33180 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 ind the size of
33190 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 the result. Do
331a0 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a not mix calls.**
331b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 to sqlite3_colu
331c0 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c mn_text() or sql
331d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 ite3_column_blob
331e0 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f () with calls to
331f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 .** sqlite3_colu
33200 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e mn_bytes16(), an
33210 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c d do not mix cal
33220 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ls to sqlite3_co
33230 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a lumn_text16().**
33240 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 with calls to s
33250 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
33260 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 tes()..**.** ^Th
33270 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 e pointers retur
33280 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e ned are valid un
33290 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 til a type conve
332a0 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a rsion occurs as.
332b0 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f ** described abo
332c0 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 ve, or until [sq
332d0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 lite3_step()] or
332e0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
332f0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 )] or.** [sqlite
33300 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 3_finalize()] is
33310 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d called. ^The m
33320 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 emory space used
33330 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 to hold strings
33340 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 .** and BLOBs is
33350 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 freed automatic
33360 61 6c 6c 79 2e 20 20 44 6f 20 3c 65 6d 3e 6e 6f ally. Do <em>no
33370 74 3c 2f 65 6d 3e 20 70 61 73 73 20 74 68 65 20 t</em> pass the
33380 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 pointers returne
33390 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 d.** from [sqlit
333a0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 e3_column_blob()
333b0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ], [sqlite3_colu
333c0 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e mn_text()], etc.
333d0 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 into.** [sqlite
333e0 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 3_free()]..**.**
333f0 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 ^(If a memory a
33400 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 llocation error
33410 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 occurs during th
33420 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 e evaluation of
33430 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 any.** of these
33440 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 routines, a defa
33450 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 ult value is ret
33460 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 urned. The defa
33470 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 ult value.** is
33480 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 either the integ
33490 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 er 0, the floati
334a0 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 ng point number
334b0 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 0.0, or a NULL.*
334c0 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 * pointer. Subs
334d0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 equent calls to
334e0 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 [sqlite3_errcode
334f0 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a ()] will return.
33500 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d ** [SQLITE_NOMEM
33510 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ].)^.*/.SQLITE_A
33520 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 PI const void *S
33530 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
33540 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f lite3_column_blo
33550 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c b(sqlite3_stmt*,
33560 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 int iCol);.SQLI
33570 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
33580 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
33590 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 3_column_bytes(s
335a0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
335b0 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f t iCol);.SQLITE_
335c0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 API int SQLITE_S
335d0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 TDCALL sqlite3_c
335e0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 olumn_bytes16(sq
335f0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
33600 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 iCol);.SQLITE_A
33610 50 49 20 64 6f 75 62 6c 65 20 53 51 4c 49 54 45 PI double SQLITE
33620 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
33630 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 _column_double(s
33640 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
33650 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f t iCol);.SQLITE_
33660 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 API int SQLITE_S
33670 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 TDCALL sqlite3_c
33680 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 olumn_int(sqlite
33690 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
336a0 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 l);.SQLITE_API s
336b0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 53 51 4c qlite3_int64 SQL
336c0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
336d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 te3_column_int64
336e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
336f0 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 int iCol);.SQLIT
33700 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 E_API const unsi
33710 67 6e 65 64 20 63 68 61 72 20 2a 53 51 4c 49 54 gned char *SQLIT
33720 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
33730 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 3_column_text(sq
33740 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
33750 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 iCol);.SQLITE_A
33760 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 PI const void *S
33770 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
33780 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
33790 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 t16(sqlite3_stmt
337a0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 *, int iCol);.SQ
337b0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
337c0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
337d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 te3_column_type(
337e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
337f0 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 nt iCol);.SQLITE
33800 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 76 61 6c _API sqlite3_val
33810 75 65 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 ue *SQLITE_STDCA
33820 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d LL sqlite3_colum
33830 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f n_value(sqlite3_
33840 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
33850 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
33860 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 F: Destroy A Pre
33870 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 pared Statement
33880 4f 62 6a 65 63 74 0a 2a 2a 20 44 45 53 54 52 55 Object.** DESTRU
33890 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 CTOR: sqlite3_st
338a0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 mt.**.** ^The sq
338b0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
338c0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c function is cal
338d0 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 led to delete a
338e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
338f0 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 ent]..** ^If the
33900 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 most recent eva
33910 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 luation of the s
33920 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 tatement encount
33930 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a ered no errors.*
33940 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 74 * or if the stat
33950 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62 ement is never b
33960 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74 een evaluated, t
33970 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 hen sqlite3_fina
33980 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a lize() returns.*
33990 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 * SQLITE_OK. ^I
339a0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e f the most recen
339b0 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 t evaluation of
339c0 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c statement S fail
339d0 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 ed, then.** sqli
339e0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 te3_finalize(S)
339f0 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 72 returns the appr
33a00 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 opriate [error c
33a10 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 ode] or.** [exte
33a20 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d nded error code]
33a30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
33a40 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 ite3_finalize(S)
33a50 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 routine can be
33a60 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f called at any po
33a70 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 int during.** th
33a80 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20 e life cycle of
33a90 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
33aa0 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 ent] S:.** befor
33ab0 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73 e statement S is
33ac0 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c ever evaluated,
33ad0 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 after.** one or
33ae0 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b more calls to [
33af0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
33b00 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63 , or after any c
33b10 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 all.** to [sqlit
33b20 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72 e3_step()] regar
33b30 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 dless of whether
33b40 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74 or not the stat
33b50 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d ement has.** com
33b60 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e pleted execution
33b70 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e ..**.** ^Invokin
33b80 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 g sqlite3_finali
33b90 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 ze() on a NULL p
33ba0 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d ointer is a harm
33bb0 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a less no-op..**.*
33bc0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f * The applicatio
33bd0 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 n must finalize
33be0 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 20 every [prepared
33bf0 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 statement] in or
33c00 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 der to avoid.**
33c10 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 resource leaks.
33c20 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f 75 It is a grievou
33c30 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20 s error for the
33c40 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 application to t
33c50 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 ry to use.** a p
33c60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
33c70 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 t after it has b
33c80 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 een finalized.
33c90 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 65 Any use of a pre
33ca0 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 pared.** stateme
33cb0 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 nt after it has
33cc0 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 been finalized c
33cd0 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 an result in und
33ce0 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e efined and.** un
33cf0 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 desirable behavi
33d00 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66 61 or such as segfa
33d10 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f ults and heap co
33d20 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c rruption..*/.SQL
33d30 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 ITE_API int SQLI
33d40 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
33d50 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 e3_finalize(sqli
33d60 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 te3_stmt *pStmt)
33d70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
33d80 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61 F: Reset A Prepa
33d90 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 red Statement Ob
33da0 6a 65 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 ject.** METHOD:
33db0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a sqlite3_stmt.**.
33dc0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 ** The sqlite3_r
33dd0 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 eset() function
33de0 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 is called to res
33df0 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 et a [prepared s
33e00 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a tatement].** obj
33e10 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 ect back to its
33e20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 initial state, r
33e30 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 eady to be re-ex
33e40 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 ecuted..** ^Any
33e50 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 SQL statement va
33e60 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 riables that had
33e70 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f values bound to
33e80 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 them using.** t
33e90 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 he [sqlite3_bind
33ea0 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f _blob | sqlite3_
33eb0 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 bind_*() API] re
33ec0 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 tain their value
33ed0 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 s..** Use [sqlit
33ee0 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 e3_clear_binding
33ef0 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 s()] to reset th
33f00 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a e bindings..**.*
33f10 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f * ^The [sqlite3_
33f20 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 reset(S)] interf
33f30 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b ace resets the [
33f40 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
33f50 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f nt] S.** back to
33f60 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f the beginning o
33f70 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a f its program..*
33f80 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 *.** ^If the mos
33f90 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f t recent call to
33fa0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 [sqlite3_step(S
33fb0 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 )] for the.** [p
33fc0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
33fd0 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 t] S returned [S
33fe0 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 QLITE_ROW] or [S
33ff0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 QLITE_DONE],.**
34000 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 or if [sqlite3_s
34010 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 tep(S)] has neve
34020 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 r before been ca
34030 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 lled on S,.** th
34040 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 en [sqlite3_rese
34050 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 t(S)] returns [S
34060 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a QLITE_OK]..**.**
34070 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 ^If the most re
34080 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 cent call to [sq
34090 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 lite3_step(S)] f
340a0 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 or the.** [prepa
340b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
340c0 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 indicated an er
340d0 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 ror, then.** [sq
340e0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 lite3_reset(S)]
340f0 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f returns an appro
34100 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f priate [error co
34110 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 de]..**.** ^The
34120 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 [sqlite3_reset(S
34130 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 )] interface doe
34140 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 s not change the
34150 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e values.** of an
34160 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f y [sqlite3_bind_
34170 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f blob|bindings] o
34180 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 n the [prepared
34190 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f statement] S..*/
341a0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
341b0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
341c0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c qlite3_reset(sql
341d0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 ite3_stmt *pStmt
341e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
341f0 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 EF: Create Or Re
34200 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 define SQL Funct
34210 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 ions.** KEYWORDS
34220 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 : {function crea
34230 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a tion routines}.*
34240 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 * KEYWORDS: {app
34250 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
34260 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a SQL function}.*
34270 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 * KEYWORDS: {app
34280 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
34290 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a SQL functions}.
342a0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
342b0 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 e3.**.** ^These
342c0 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 functions (colle
342d0 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 ctively known as
342e0 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 "function creat
342f0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a ion routines").*
34300 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 * are used to ad
34310 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 d SQL functions
34320 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 or aggregates or
34330 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 to redefine the
34340 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 behavior.** of
34350 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e existing SQL fun
34360 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 ctions or aggreg
34370 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 ates. The only
34380 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 77 differences betw
34390 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 een.** these rou
343a0 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 65 tines are the te
343b0 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 xt encoding expe
343c0 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 cted for.** the
343d0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
343e0 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 (the name of th
343f0 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 e function being
34400 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 created).** and
34410 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72 the presence or
34420 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65 absence of a de
34430 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 structor callbac
34440 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 k for.** the app
34450 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f lication data po
34460 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 inter..**.** ^Th
34470 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
34480 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 r is the [databa
34490 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 se connection] t
344a0 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a o which the SQL.
344b0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 ** function is t
344c0 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 o be added. ^If
344d0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 an application
344e0 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f uses more than o
344f0 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 ne database.** c
34500 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 onnection then a
34510 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
34520 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 ed SQL functions
34530 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a must be added.*
34540 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 * to each databa
34550 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 se connection se
34560 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 parately..**.**
34570 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 ^The second para
34580 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d meter is the nam
34590 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e e of the SQL fun
345a0 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 ction to be crea
345b0 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 ted or.** redefi
345c0 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 ned. ^The lengt
345d0 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 h of the name is
345e0 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 limited to 255
345f0 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38 bytes in a UTF-8
34600 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69 .** representati
34610 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 on, exclusive of
34620 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e the zero-termin
34630 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 ator. ^Note tha
34640 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 t the name.** le
34650 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e ngth limit is in
34660 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f UTF-8 bytes, no
34670 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72 t characters nor
34680 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20 UTF-16 bytes.
34690 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 .** ^Any attempt
346a0 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e to create a fun
346b0 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e ction with a lon
346c0 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c ger name.** will
346d0 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 result in [SQLI
346e0 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 TE_MISUSE] being
346f0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
34700 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61 ^The third para
34710 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 meter (nArg).**
34720 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 is the number of
34730 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 arguments that
34740 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
34750 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 or.** aggregate
34760 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 takes. ^If this
34770 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 parameter is -1
34780 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 , then the SQL f
34790 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 unction or.** ag
347a0 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 gregate may take
347b0 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 any number of a
347c0 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e rguments between
347d0 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0 and the limit
347e0 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 .** set by [sqli
347f0 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 te3_limit]([SQLI
34800 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f TE_LIMIT_FUNCTIO
34810 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 N_ARG]). If the
34820 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 third.** parame
34830 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e ter is less than
34840 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 -1 or greater t
34850 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 han 127 then the
34860 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 behavior is.**
34870 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a undefined..**.**
34880 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 ^The fourth par
34890 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 ameter, eTextRep
348a0 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 , specifies what
348b0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 .** [SQLITE_UTF8
348c0 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 | text encoding
348d0 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 ] this SQL funct
348e0 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a ion prefers for.
348f0 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 ** its parameter
34900 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 s. The applicat
34910 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74 20 74 ion should set t
34920 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f his parameter to
34930 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 .** [SQLITE_UTF1
34940 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75 6e 63 6LE] if the func
34950 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 tion implementat
34960 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 ion invokes .**
34970 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 [sqlite3_value_t
34980 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e ext16le()] on an
34990 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49 input, or [SQLI
349a0 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66 20 74 TE_UTF16BE] if t
349b0 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 he.** implementa
349c0 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71 tion invokes [sq
349d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
349e0 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 16be()] on an in
349f0 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 put, or.** [SQLI
34a00 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b 73 71 TE_UTF16] if [sq
34a10 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
34a20 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 6f 16()] is used, o
34a30 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a r [SQLITE_UTF8].
34a40 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20 20 5e ** otherwise. ^
34a50 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e The same SQL fun
34a60 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 ction may be reg
34a70 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 istered multiple
34a80 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20 times using.**
34a90 64 69 66 66 65 72 65 6e 74 20 70 72 65 66 65 72 different prefer
34aa0 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e red text encodin
34ab0 67 73 2c 20 77 69 74 68 20 64 69 66 66 65 72 65 gs, with differe
34ac0 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f nt implementatio
34ad0 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65 ns for.** each e
34ae0 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 ncoding..** ^Whe
34af0 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 n multiple imple
34b00 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 mentations of th
34b10 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 e same function
34b20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 are available, S
34b30 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 QLite.** will pi
34b40 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 ck the one that
34b50 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 involves the lea
34b60 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 st amount of dat
34b70 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a a conversion..**
34b80 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 .** ^The fourth
34b90 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 6f 70 parameter may op
34ba0 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64 tionally be ORed
34bb0 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 with [SQLITE_DE
34bc0 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 TERMINISTIC].**
34bd0 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74 20 74 to signal that t
34be0 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c he function will
34bf0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 always return t
34c00 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74 20 67 he same result g
34c10 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 iven.** the same
34c20 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e 20 61 inputs within a
34c30 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 single SQL stat
34c40 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c ement. Most SQL
34c50 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a functions are.*
34c60 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e * deterministic.
34c70 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b The built-in [
34c80 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75 random()] SQL fu
34c90 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65 78 61 nction is an exa
34ca0 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e mple of a.** fun
34cb0 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f ction that is no
34cc0 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e t deterministic.
34cd0 20 20 54 68 65 20 53 51 4c 69 74 65 20 71 75 65 The SQLite que
34ce0 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20 61 62 ry planner is ab
34cf0 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d le to.** perform
34d00 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 additional opti
34d10 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74 mizations on det
34d20 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e 63 74 erministic funct
34d30 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 ions, so use.**
34d40 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 of the [SQLITE_D
34d50 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c ETERMINISTIC] fl
34d60 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 ag is recommende
34d70 64 20 77 68 65 72 65 20 70 6f 73 73 69 62 6c 65 d where possible
34d80 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 ..**.** ^(The fi
34d90 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 fth parameter is
34da0 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f an arbitrary po
34db0 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c inter. The impl
34dc0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 ementation of th
34dd0 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 e.** function ca
34de0 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f n gain access to
34df0 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 this pointer us
34e00 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 ing [sqlite3_use
34e10 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a r_data()].)^.**.
34e20 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73 ** ^The sixth, s
34e30 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74 eventh and eight
34e40 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 h parameters, xF
34e50 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 unc, xStep and x
34e60 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f Final, are.** po
34e70 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 inters to C-lang
34e80 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 uage functions t
34e90 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 hat implement th
34ea0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f e SQL function o
34eb0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 r.** aggregate.
34ec0 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 ^A scalar SQL fu
34ed0 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 nction requires
34ee0 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f an implementatio
34ef0 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a n of the xFunc.*
34f00 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b * callback only;
34f10 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d NULL pointers m
34f20 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73 ust be passed as
34f30 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 the xStep and x
34f40 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 Final.** paramet
34f50 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 ers. ^An aggrega
34f60 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 te SQL function
34f70 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c requires an impl
34f80 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 ementation of xS
34f90 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 tep.** and xFina
34fa0 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 l and NULL point
34fb0 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 er must be passe
34fc0 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f d for xFunc. ^To
34fd0 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 delete an exist
34fe0 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 ing.** SQL funct
34ff0 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 ion or aggregate
35000 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e , pass NULL poin
35010 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 ters for all thr
35020 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 ee function.** c
35030 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 allbacks..**.**
35040 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70 ^(If the ninth p
35050 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
35060 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
35070 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 ion_v2() is not
35080 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 NULL,.** then it
35090 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 66 is destructor f
350a0 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 or the applicati
350b0 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e on data pointer.
350c0 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63 .** The destruc
350d0 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 tor is invoked w
350e0 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e hen the function
350f0 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74 is deleted, eit
35100 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 her by being.**
35110 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 overloaded or wh
35120 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
35130 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 connection close
35140 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 s.)^.** ^The des
35150 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 tructor is also
35160 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63 invoked if the c
35170 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 all to.** sqlite
35180 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
35190 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a n_v2() fails..**
351a0 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 72 ^When the destr
351b0 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f uctor callback o
351c0 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 61 f the tenth para
351d0 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 meter is invoked
351e0 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 , it.** is passe
351f0 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d d a single argum
35200 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 63 ent which is a c
35210 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69 opy of the appli
35220 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 cation data .**
35230 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 pointer which wa
35240 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72 61 s the fifth para
35250 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
35260 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
35270 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 _v2()..**.** ^It
35280 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f is permitted to
35290 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 register multip
352a0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f le implementatio
352b0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a ns of the same.*
352c0 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 * functions with
352d0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 the same name b
352e0 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64 ut with either d
352f0 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 iffering numbers
35300 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 of.** arguments
35310 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 or differing pr
35320 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 eferred text enc
35330 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 odings. ^SQLite
35340 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 will use.** the
35350 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
35360 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c that most closel
35370 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 y matches the wa
35380 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a y in which the.*
35390 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 * SQL function i
353a0 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 s used. ^A func
353b0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 tion implementat
353c0 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e ion with a non-n
353d0 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 egative.** nArg
353e0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 parameter is a b
353f0 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e etter match than
35400 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c a function impl
35410 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a ementation with.
35420 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 ** a negative nA
35430 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e rg. ^A function
35440 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65 where the prefe
35450 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 rred text encodi
35460 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 ng.** matches th
35470 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 e database encod
35480 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a ing is a better.
35490 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 ** match than a
354a0 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 function where t
354b0 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 he encoding is d
354c0 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e ifferent. .** ^
354d0 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 A function where
354e0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 the encoding di
354f0 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 fference is betw
35500 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 een UTF16le and
35510 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 UTF16be.** is a
35520 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 closer match tha
35530 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 n a function whe
35540 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 re the encoding
35550 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a difference is.**
35560 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e between UTF8 an
35570 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e d UTF16..**.** ^
35580 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f Built-in functio
35590 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f ns may be overlo
355a0 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c aded by new appl
355b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
355c0 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a functions..**.**
355d0 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e ^An application
355e0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
355f0 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 n is permitted t
35600 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 o call other.**
35610 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
35620 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 s. However, suc
35630 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 h calls must not
35640 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 .** close the da
35650 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
35660 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f n nor finalize o
35670 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 r reset the prep
35680 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e ared.** statemen
35690 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 t in which the f
356a0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 unction is runni
356b0 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 ng..*/.SQLITE_AP
356c0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
356d0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 72 65 CALL sqlite3_cre
356e0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 ate_function(.
356f0 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 sqlite3 *db,. c
35700 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 onst char *zFunc
35710 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 tionName,. int
35720 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 nArg,. int eTex
35730 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 tRep,. void *pA
35740 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 pp,. void (*xFu
35750 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 nc)(sqlite3_cont
35760 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 ext*,int,sqlite3
35770 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 _value**),. voi
35780 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 d (*xStep)(sqlit
35790 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c e3_context*,int,
357a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 sqlite3_value**)
357b0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 ,. void (*xFina
357c0 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 l)(sqlite3_conte
357d0 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 xt*).);.SQLITE_A
357e0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 PI int SQLITE_ST
357f0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 72 DCALL sqlite3_cr
35800 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 eate_function16(
35810 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a . sqlite3 *db,.
35820 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 const void *zF
35830 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 unctionName,. i
35840 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 nt nArg,. int e
35850 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 TextRep,. void
35860 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a *pApp,. void (*
35870 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 xFunc)(sqlite3_c
35880 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 ontext*,int,sqli
35890 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 te3_value**),.
358a0 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 void (*xStep)(sq
358b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 lite3_context*,i
358c0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt,sqlite3_value
358d0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 **),. void (*xF
358e0 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f inal)(sqlite3_co
358f0 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 ntext*).);.SQLIT
35900 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
35910 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
35920 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
35930 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a _v2(. sqlite3 *
35940 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 db,. const char
35950 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c *zFunctionName,
35960 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 . int nArg,. i
35970 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 nt eTextRep,. v
35980 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 oid *pApp,. voi
35990 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 d (*xFunc)(sqlit
359a0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c e3_context*,int,
359b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 sqlite3_value**)
359c0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 ,. void (*xStep
359d0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 )(sqlite3_contex
359e0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 t*,int,sqlite3_v
359f0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 alue**),. void
35a00 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 (*xFinal)(sqlite
35a10 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 3_context*),. v
35a20 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 oid(*xDestroy)(v
35a30 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 oid*).);../*.**
35a40 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 CAPI3REF: Text E
35a50 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 ncodings.**.** T
35a60 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 hese constant de
35a70 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 fine integer cod
35a80 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e es that represen
35a90 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a t the various.**
35aa0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 text encodings
35ab0 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c supported by SQL
35ac0 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ite..*/.#define
35ad0 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 SQLITE_UTF8
35ae0 20 20 20 20 20 20 31 20 20 20 20 2f 2a 20 49 4d 1 /* IM
35af0 50 3a 20 52 2d 33 37 35 31 34 2d 33 35 35 36 36 P: R-37514-35566
35b00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
35b10 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 TE_UTF16LE
35b20 20 20 32 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2 /* IMP: R
35b30 2d 30 33 33 37 31 2d 33 37 36 33 37 20 2a 2f 0a -03371-37637 */.
35b40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 #define SQLITE_U
35b50 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33 20 TF16BE 3
35b60 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 35 31 39 /* IMP: R-519
35b70 37 31 2d 33 34 31 35 34 20 2a 2f 0a 23 64 65 66 71-34154 */.#def
35b80 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 ine SQLITE_UTF16
35b90 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 4 /
35ba0 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 * Use native byt
35bb0 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 e order */.#defi
35bc0 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 ne SQLITE_ANY
35bd0 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 5 /*
35be0 20 44 65 70 72 65 63 61 74 65 64 20 2a 2f 0a 23 Deprecated */.#
35bf0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 define SQLITE_UT
35c00 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 F16_ALIGNED 8
35c10 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 /* sqlite3_cre
35c20 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e ate_collation on
35c30 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ly */../*.** CAP
35c40 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 I3REF: Function
35c50 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 Flags.**.** Thes
35c60 65 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 e constants may
35c70 62 65 20 4f 52 65 64 20 74 6f 67 65 74 68 65 72 be ORed together
35c80 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 with the .** [S
35c90 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 70 72 65 QLITE_UTF8 | pre
35ca0 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f ferred text enco
35cb0 64 69 6e 67 5d 20 61 73 20 74 68 65 20 66 6f 75 ding] as the fou
35cc0 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 rth argument.**
35cd0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 to [sqlite3_crea
35ce0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 te_function()],
35cf0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
35d00 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 20 6f function16()], o
35d10 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 r.** [sqlite3_cr
35d20 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 eate_function_v2
35d30 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ()]..*/.#define
35d40 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 SQLITE_DETERMINI
35d50 53 54 49 43 20 20 20 20 30 78 38 30 30 0a 0a 2f STIC 0x800../
35d60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
35d70 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 eprecated Functi
35d80 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 ons.** DEPRECATE
35d90 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 D.**.** These fu
35da0 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 nctions are [dep
35db0 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 recated]. In or
35dc0 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a der to maintain.
35dd0 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d ** backwards com
35de0 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 patibility with
35df0 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 older code, thes
35e00 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 e functions cont
35e10 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 inue .** to be s
35e20 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 upported. Howev
35e30 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 er, new applicat
35e40 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 ions should avoi
35e50 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 d.** the use of
35e60 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e these functions.
35e70 20 20 54 6f 20 65 6e 63 6f 75 72 61 67 65 20 70 To encourage p
35e80 72 6f 67 72 61 6d 6d 65 72 73 20 74 6f 20 61 76 rogrammers to av
35e90 6f 69 64 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e oid.** these fun
35ea0 63 74 69 6f 6e 73 2c 20 77 65 20 77 69 6c 6c 20 ctions, we will
35eb0 6e 6f 74 20 65 78 70 6c 61 69 6e 20 77 68 61 74 not explain what
35ec0 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 they do..*/.#if
35ed0 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 ndef SQLITE_OMIT
35ee0 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49 _DEPRECATED.SQLI
35ef0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 TE_API SQLITE_DE
35f00 50 52 45 43 41 54 45 44 20 69 6e 74 20 53 51 4c PRECATED int SQL
35f10 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
35f20 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
35f30 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 unt(sqlite3_cont
35f40 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 ext*);.SQLITE_AP
35f50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 I SQLITE_DEPRECA
35f60 54 45 44 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 TED int SQLITE_S
35f70 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 TDCALL sqlite3_e
35f80 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 xpired(sqlite3_s
35f90 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 tmt*);.SQLITE_AP
35fa0 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 I SQLITE_DEPRECA
35fb0 54 45 44 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 TED int SQLITE_S
35fc0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74 TDCALL sqlite3_t
35fd0 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 ransfer_bindings
35fe0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
35ff0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a sqlite3_stmt*);.
36000 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
36010 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 E_DEPRECATED int
36020 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
36030 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 sqlite3_global_r
36040 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 ecover(void);.SQ
36050 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
36060 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 DEPRECATED void
36070 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
36080 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c qlite3_thread_cl
36090 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c eanup(void);.SQL
360a0 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 ITE_API SQLITE_D
360b0 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 53 51 EPRECATED int SQ
360c0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
360d0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 ite3_memory_alar
360e0 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c m(void(*)(void*,
360f0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e sqlite3_int64,in
36100 74 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 t),.
36110 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 2a 2c void*,
36120 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a sqlite3_int64);.
36130 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 #endif../*.** CA
36140 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e PI3REF: Obtainin
36150 67 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 g SQL Values.**
36160 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f METHOD: sqlite3_
36170 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 value.**.** The
36180 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 C-language imple
36190 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c mentation of SQL
361a0 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 functions and a
361b0 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a ggregates uses.*
361c0 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e * this set of in
361d0 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 terface routines
361e0 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 to access the p
361f0 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 arameter values
36200 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 on.** the functi
36210 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e on or aggregate.
36220 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 .**.** The xFu
36230 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 nc (for scalar f
36240 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 unctions) or xSt
36250 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 ep (for aggregat
36260 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a es) parameters.*
36270 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 * to [sqlite3_cr
36280 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d eate_function()]
36290 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 and [sqlite3_cr
362a0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 eate_function16(
362b0 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c )].** define cal
362c0 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c lbacks that impl
362d0 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 ement the SQL fu
362e0 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 nctions and aggr
362f0 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 egates..** The 3
36300 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 rd parameter to
36310 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 these callbacks
36320 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 is an array of p
36330 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 ointers to.** [p
36340 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
36350 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e _value] objects.
36360 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b There is one [
36370 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
36380 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 bject for.** eac
36390 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 h parameter to t
363a0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e he SQL function.
363b0 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 These routines
363c0 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 are used to.**
363d0 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 extract values f
363e0 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 rom the [sqlite3
363f0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e _value] objects.
36400 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
36410 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 tines work only
36420 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 with [protected
36430 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
36440 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 bjects..** Any a
36450 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 ttempt to use th
36460 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 ese routines on
36470 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 an [unprotected
36480 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a sqlite3_value].*
36490 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 * object results
364a0 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 in undefined be
364b0 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 havior..**.** ^T
364c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f hese routines wo
364d0 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 rk just like the
364e0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b corresponding [
364f0 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 column access fu
36500 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 nctions].** exce
36510 70 74 20 74 68 61 74 20 74 68 65 73 65 20 72 6f pt that these ro
36520 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 utines take a si
36530 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 ngle [protected
36540 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
36550 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 bject.** pointer
36560 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 instead of a [s
36570 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f qlite3_stmt*] po
36580 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 inter and an int
36590 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 eger column numb
365a0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 er..**.** ^The s
365b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
365c0 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 t16() interface
365d0 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 extracts a UTF-1
365e0 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 6 string.** in t
365f0 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f he native byte-o
36600 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 rder of the host
36610 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a machine. ^The.
36620 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ** sqlite3_value
36630 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 _text16be() and
36640 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
36650 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 xt16le() interfa
36660 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 ces.** extract U
36670 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 TF-16 strings as
36680 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 big-endian and
36690 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 little-endian re
366a0 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a spectively..**.*
366b0 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f * ^(The sqlite3_
366c0 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 value_numeric_ty
366d0 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 pe() interface a
366e0 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 ttempts to apply
366f0 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 .** numeric affi
36700 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 nity to the valu
36710 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 e. This means t
36720 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 hat an attempt i
36730 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e s.** made to con
36740 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 vert the value t
36750 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 o an integer or
36760 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 floating point.
36770 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f If.** such a co
36780 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 nversion is poss
36790 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 ible without los
367a0 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e s of information
367b0 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f (in other.** wo
367c0 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 rds, if the valu
367d0 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 e is a string th
367e0 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 at looks like a
367f0 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 number).** then
36800 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 the conversion i
36810 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 s performed. Ot
36820 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 herwise no conve
36830 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a rsion occurs..**
36840 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 The [SQLITE_INT
36850 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d EGER | datatype]
36860 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f after conversio
36870 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e n is returned.)^
36880 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 .**.** Please pa
36890 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 y particular att
368a0 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 ention to the fa
368b0 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e ct that the poin
368c0 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 ter returned.**
368d0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 from [sqlite3_va
368e0 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 lue_blob()], [sq
368f0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
36900 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 ()], or.** [sqli
36910 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 te3_value_text16
36920 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c ()] can be inval
36930 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73 idated by a subs
36940 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a equent call to.*
36950 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 * [sqlite3_value
36960 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 _bytes()], [sqli
36970 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 te3_value_bytes1
36980 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 6()], [sqlite3_v
36990 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a alue_text()],.**
369a0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c or [sqlite3_val
369b0 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a ue_text16()]..**
369c0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
369d0 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 es must be calle
369e0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 d from the same
369f0 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 thread as.** the
36a00 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 SQL function th
36a10 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 at supplied the
36a20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d [sqlite3_value*]
36a30 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a parameters..*/.
36a40 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
36a50 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 void *SQLITE_ST
36a60 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 DCALL sqlite3_va
36a70 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 lue_blob(sqlite3
36a80 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 _value*);.SQLITE
36a90 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f _API int SQLITE_
36aa0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
36ab0 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 value_bytes(sqli
36ac0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c te3_value*);.SQL
36ad0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 ITE_API int SQLI
36ae0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
36af0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 e3_value_bytes16
36b00 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
36b10 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 ;.SQLITE_API dou
36b20 62 6c 65 20 53 51 4c 49 54 45 5f 53 54 44 43 41 ble SQLITE_STDCA
36b30 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 LL sqlite3_value
36b40 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f _double(sqlite3_
36b50 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f value*);.SQLITE_
36b60 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 API int SQLITE_S
36b70 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 TDCALL sqlite3_v
36b80 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 alue_int(sqlite3
36b90 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 _value*);.SQLITE
36ba0 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 _API sqlite3_int
36bb0 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 64 SQLITE_STDCAL
36bc0 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f L sqlite3_value_
36bd0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 int64(sqlite3_va
36be0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 lue*);.SQLITE_AP
36bf0 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 I const unsigned
36c00 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 char *SQLITE_ST
36c10 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 DCALL sqlite3_va
36c20 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 lue_text(sqlite3
36c30 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 _value*);.SQLITE
36c40 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 _API const void
36c50 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 *SQLITE_STDCALL
36c60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
36c70 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c xt16(sqlite3_val
36c80 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ue*);.SQLITE_API
36c90 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c const void *SQL
36ca0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
36cb0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 te3_value_text16
36cc0 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 le(sqlite3_value
36cd0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 *);.SQLITE_API c
36ce0 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 onst void *SQLIT
36cf0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
36d00 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 3_value_text16be
36d10 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
36d20 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
36d30 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
36d40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 sqlite3_value_ty
36d50 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 pe(sqlite3_value
36d60 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 *);.SQLITE_API i
36d70 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c nt SQLITE_STDCAL
36d80 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f L sqlite3_value_
36d90 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c numeric_type(sql
36da0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f ite3_value*);../
36db0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 *.** CAPI3REF: F
36dc0 69 6e 64 69 6e 67 20 54 68 65 20 53 75 62 74 79 inding The Subty
36dd0 70 65 20 4f 66 20 53 51 4c 20 56 61 6c 75 65 73 pe Of SQL Values
36de0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
36df0 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 te3_value.**.**
36e00 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 The sqlite3_valu
36e10 65 5f 73 75 62 74 79 70 65 28 56 29 20 66 75 6e e_subtype(V) fun
36e20 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 ction returns th
36e30 65 20 73 75 62 74 79 70 65 20 66 6f 72 0a 2a 2a e subtype for.**
36e40 20 61 6e 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e an [application
36e50 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e -defined SQL fun
36e60 63 74 69 6f 6e 5d 20 61 72 67 75 6d 65 6e 74 20 ction] argument
36e70 56 2e 20 20 54 68 65 20 73 75 62 74 79 70 65 0a V. The subtype.
36e80 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 63 ** information c
36e90 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 70 61 an be used to pa
36ea0 73 73 20 61 20 6c 69 6d 69 74 65 64 20 61 6d 6f ss a limited amo
36eb0 75 6e 74 20 6f 66 20 63 6f 6e 74 65 78 74 20 66 unt of context f
36ec0 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 53 51 4c 20 66 rom.** one SQL f
36ed0 75 6e 63 74 69 6f 6e 20 74 6f 20 61 6e 6f 74 68 unction to anoth
36ee0 65 72 2e 20 20 55 73 65 20 74 68 65 20 5b 73 71 er. Use the [sq
36ef0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 73 75 62 lite3_result_sub
36f00 74 79 70 65 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 type()].** routi
36f10 6e 65 20 74 6f 20 73 65 74 20 74 68 65 20 73 75 ne to set the su
36f20 62 74 79 70 65 20 66 6f 72 20 74 68 65 20 72 65 btype for the re
36f30 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 61 6e turn value of an
36f40 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a SQL function..*
36f50 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 *.** SQLite make
36f60 73 20 6e 6f 20 75 73 65 20 6f 66 20 73 75 62 74 s no use of subt
36f70 79 70 65 20 69 74 73 65 6c 66 2e 20 20 49 74 20 ype itself. It
36f80 6d 65 72 65 6c 79 20 70 61 73 73 65 73 20 74 68 merely passes th
36f90 65 20 73 75 62 74 79 70 65 0a 2a 2a 20 66 72 6f e subtype.** fro
36fa0 6d 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 m the result of
36fb0 6f 6e 65 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e one [application
36fc0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e -defined SQL fun
36fd0 63 74 69 6f 6e 5d 20 69 6e 74 6f 20 74 68 65 0a ction] into the.
36fe0 2a 2a 20 69 6e 70 75 74 20 6f 66 20 61 6e 6f 74 ** input of anot
36ff0 68 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 her..*/.SQLITE_A
37000 50 49 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 PI unsigned int
37010 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
37020 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 73 75 62 qlite3_value_sub
37030 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c type(sqlite3_val
37040 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ue*);../*.** CAP
37050 49 33 52 45 46 3a 20 43 6f 70 79 20 41 6e 64 20 I3REF: Copy And
37060 46 72 65 65 20 53 51 4c 20 56 61 6c 75 65 73 0a Free SQL Values.
37070 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
37080 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 5e e3_value.**.** ^
37090 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 The sqlite3_valu
370a0 65 5f 64 75 70 28 56 29 20 69 6e 74 65 72 66 61 e_dup(V) interfa
370b0 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 ce makes a copy
370c0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
370d0 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 value].** object
370e0 20 44 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 D and returns a
370f0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 pointer to that
37100 20 63 6f 70 79 2e 20 20 5e 54 68 65 20 5b 73 71 copy. ^The [sq
37110 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 72 65 74 lite3_value] ret
37120 75 72 6e 65 64 0a 2a 2a 20 69 73 20 61 20 5b 70 urned.** is a [p
37130 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
37140 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 65 _value] object e
37150 76 65 6e 20 69 66 20 74 68 65 20 69 6e 70 75 74 ven if the input
37160 20 69 73 20 6e 6f 74 2e 0a 2a 2a 20 5e 54 68 65 is not..** ^The
37170 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 sqlite3_value_d
37180 75 70 28 56 29 20 69 6e 74 65 72 66 61 63 65 20 up(V) interface
37190 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 returns NULL if
371a0 56 20 69 73 20 4e 55 4c 4c 20 6f 72 20 69 66 20 V is NULL or if
371b0 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f a.** memory allo
371c0 63 61 74 69 6f 6e 20 66 61 69 6c 73 2e 0a 2a 2a cation fails..**
371d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
371e0 5f 76 61 6c 75 65 5f 66 72 65 65 28 56 29 20 69 _value_free(V) i
371f0 6e 74 65 72 66 61 63 65 20 66 72 65 65 73 20 61 nterface frees a
37200 6e 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 n [sqlite3_value
37210 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 72 65 76 ] object.** prev
37220 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 iously obtained
37230 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 from [sqlite3_va
37240 6c 75 65 5f 64 75 70 28 29 5d 2e 20 20 5e 49 66 lue_dup()]. ^If
37250 20 56 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 V is a NULL poi
37260 6e 74 65 72 0a 2a 2a 20 74 68 65 6e 20 73 71 6c nter.** then sql
37270 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 ite3_value_free(
37280 56 29 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 V) is a harmless
37290 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 54 no-op..*/.SQLIT
372a0 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50 E_API SQLITE_EXP
372b0 45 52 49 4d 45 4e 54 41 4c 20 73 71 6c 69 74 65 ERIMENTAL sqlite
372c0 33 5f 76 61 6c 75 65 20 2a 53 51 4c 49 54 45 5f 3_value *SQLITE_
372d0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
372e0 76 61 6c 75 65 5f 64 75 70 28 63 6f 6e 73 74 20 value_dup(const
372f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
37300 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 .SQLITE_API SQLI
37310 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 TE_EXPERIMENTAL
37320 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 void SQLITE_STDC
37330 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ALL sqlite3_valu
37340 65 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f 76 e_free(sqlite3_v
37350 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 alue*);../*.** C
37360 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 API3REF: Obtain
37370 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 Aggregate Functi
37380 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 20 4d 45 on Context.** ME
37390 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f THOD: sqlite3_co
373a0 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c ntext.**.** Impl
373b0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 ementations of a
373c0 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e ggregate SQL fun
373d0 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a ctions use this.
373e0 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c ** routine to al
373f0 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f locate memory fo
37400 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 r storing their
37410 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 state..**.** ^Th
37420 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 e first time the
37430 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 sqlite3_aggrega
37440 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 te_context(C,N)
37450 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 routine is calle
37460 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 d .** for a part
37470 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 icular aggregate
37480 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 function, SQLit
37490 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e e.** allocates N
374a0 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f of memory, zero
374b0 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f es out that memo
374c0 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 ry, and returns
374d0 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 a pointer.** to
374e0 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 the new memory.
374f0 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 ^On second and s
37500 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 ubsequent calls
37510 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 to.** sqlite3_ag
37520 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 gregate_context(
37530 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 ) for the same a
37540 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f ggregate functio
37550 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 n instance,.** t
37560 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 he same buffer i
37570 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c s returned. Sql
37580 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
37590 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d ontext() is norm
375a0 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f ally.** called o
375b0 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76 nce for each inv
375c0 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 ocation of the x
375d0 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e Step callback an
375e0 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 d then one.** la
375f0 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 st time when the
37600 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b xFinal callback
37610 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 is invoked. ^(
37620 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 When no rows mat
37630 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 ch.** an aggrega
37640 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 78 53 te query, the xS
37650 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f tep() callback o
37660 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 f the aggregate
37670 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c function.** impl
37680 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 ementation is ne
37690 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 ver called and x
376a0 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 Final() is calle
376b0 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a d exactly once..
376c0 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65 ** In those case
376d0 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 s, sqlite3_aggre
376e0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d gate_context() m
376f0 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66 ight be called f
37700 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 or the.** first
37710 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e time from within
37720 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a xFinal().)^.**.
37730 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
37740 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 aggregate_contex
37750 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 t(C,N) routine r
37760 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f eturns a NULL po
37770 69 6e 74 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66 inter .** when f
37780 69 72 73 74 20 63 61 6c 6c 65 64 20 69 66 20 4e irst called if N
37790 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 is less than or
377a0 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f equal to zero o
377b0 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a r if a memory.**
377c0 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 allocate error
377d0 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 occurs..**.** ^(
377e0 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 The amount of sp
377f0 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 ace allocated by
37800 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 sqlite3_aggrega
37810 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 te_context(C,N)
37820 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 is.** determined
37830 20 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65 by the N parame
37840 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63 ter on first suc
37850 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 cessful call. C
37860 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 hanging the.** v
37870 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 alue of N in sub
37880 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 sequent call to
37890 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 sqlite3_aggregat
378a0 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68 e_context() with
378b0 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 in.** the same a
378c0 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f ggregate functio
378d0 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 n instance will
378e0 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d not resize the m
378f0 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 emory.** allocat
37900 69 6f 6e 2e 29 5e 20 20 57 69 74 68 69 6e 20 74 ion.)^ Within t
37910 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 he xFinal callba
37920 63 6b 2c 20 69 74 20 69 73 20 63 75 73 74 6f 6d ck, it is custom
37930 61 72 79 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d ary to set.** N=
37940 30 20 69 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 0 in calls to sq
37950 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
37960 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 73 6f 20 context(C,N) so
37970 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e that no .** poin
37980 74 6c 65 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c tless memory all
37990 6f 63 61 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a ocations occur..
379a0 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 **.** ^SQLite au
379b0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 tomatically free
379c0 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c s the memory all
379d0 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 ocated by .** sq
379e0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
379f0 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 context() when t
37a00 68 65 20 61 67 67 72 65 67 61 74 65 20 71 75 65 he aggregate que
37a10 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a ry concludes..**
37a20 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 .** The first pa
37a30 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 rameter must be
37a40 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a a copy of the.**
37a50 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 [sqlite3_contex
37a60 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e t | SQL function
37a70 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 context] that i
37a80 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 s the first para
37a90 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 meter.** to the
37aa0 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 xStep or xFinal
37ab0 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 callback routine
37ac0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 that implements
37ad0 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a the aggregate.*
37ae0 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a * function..**.*
37af0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d * This routine m
37b00 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 ust be called fr
37b10 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 om the same thre
37b20 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 ad in which.** t
37b30 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c he aggregate SQL
37b40 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e function is run
37b50 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f ning..*/.SQLITE_
37b60 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 API void *SQLITE
37b70 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
37b80 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 _aggregate_conte
37b90 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 xt(sqlite3_conte
37ba0 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 xt*, int nBytes)
37bb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
37bc0 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 F: User Data For
37bd0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 Functions.** ME
37be0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f THOD: sqlite3_co
37bf0 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ntext.**.** ^The
37c00 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 sqlite3_user_da
37c10 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 ta() interface r
37c20 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 eturns a copy of
37c30 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 .** the pointer
37c40 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73 that was the pUs
37c50 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 erData parameter
37c60 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 (the 5th parame
37c70 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b ter).** of the [
37c80 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
37c90 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e unction()].** an
37ca0 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 d [sqlite3_creat
37cb0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 e_function16()]
37cc0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 routines that or
37cd0 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 iginally.** regi
37ce0 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 stered the appli
37cf0 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 cation defined f
37d00 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 unction..**.** T
37d10 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 his routine must
37d20 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 be called from
37d30 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 the same thread
37d40 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 in which.** the
37d50 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
37d60 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 ned function is
37d70 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 running..*/.SQLI
37d80 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c TE_API void *SQL
37d90 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
37da0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 te3_user_data(sq
37db0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b lite3_context*);
37dc0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
37dd0 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 : Database Conne
37de0 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 ction For Functi
37df0 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 ons.** METHOD: s
37e00 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a qlite3_context.*
37e10 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
37e20 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 3_context_db_han
37e30 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 dle() interface
37e40 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f returns a copy o
37e50 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 f.** the pointer
37e60 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 to the [databas
37e70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 e connection] (t
37e80 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 he 1st parameter
37e90 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c ).** of the [sql
37ea0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
37eb0 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b tion()].** and [
37ec0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
37ed0 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 unction16()] rou
37ee0 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 tines that origi
37ef0 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 nally.** registe
37f00 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 red the applicat
37f10 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 ion defined func
37f20 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f tion..*/.SQLITE_
37f30 41 50 49 20 73 71 6c 69 74 65 33 20 2a 53 51 4c API sqlite3 *SQL
37f40 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
37f50 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 te3_context_db_h
37f60 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f andle(sqlite3_co
37f70 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 ntext*);../*.**
37f80 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 CAPI3REF: Functi
37f90 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 on Auxiliary Dat
37fa0 61 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c a.** METHOD: sql
37fb0 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a ite3_context.**.
37fc0 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f ** These functio
37fd0 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 ns may be used b
37fe0 79 20 28 6e 6f 6e 2d 61 67 67 72 65 67 61 74 65 y (non-aggregate
37ff0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 ) SQL functions
38000 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 to.** associate
38010 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72 metadata with ar
38020 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 gument values. I
38030 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 f the same value
38040 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a is passed to.**
38050 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 multiple invoca
38060 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d tions of the sam
38070 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 e SQL function d
38080 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 uring query exec
38090 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 ution, under.**
380a0 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 some circumstanc
380b0 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 es the associate
380c0 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 d metadata may b
380d0 65 20 70 72 65 73 65 72 76 65 64 2e 20 20 41 6e e preserved. An
380e0 20 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77 example.** of w
380f0 68 65 72 65 20 74 68 69 73 20 6d 69 67 68 74 20 here this might
38100 62 65 20 75 73 65 66 75 6c 20 69 73 20 69 6e 20 be useful is in
38110 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 a regular-expres
38120 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 0a 2a 2a sion matching.**
38130 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 function. The c
38140 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 ompiled version
38150 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 of the regular e
38160 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 xpression can be
38170 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 stored as.** me
38180 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 tadata associate
38190 64 20 77 69 74 68 20 74 68 65 20 70 61 74 74 65 d with the patte
381a0 72 6e 20 73 74 72 69 6e 67 2e 20 20 0a 2a 2a 20 rn string. .**
381b0 54 68 65 6e 20 61 73 20 6c 6f 6e 67 20 61 73 20 Then as long as
381c0 74 68 65 20 70 61 74 74 65 72 6e 20 73 74 72 69 the pattern stri
381d0 6e 67 20 72 65 6d 61 69 6e 73 20 74 68 65 20 73 ng remains the s
381e0 61 6d 65 2c 0a 2a 2a 20 74 68 65 20 63 6f 6d 70 ame,.** the comp
381f0 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 iled regular exp
38200 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 ression can be r
38210 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c eused on multipl
38220 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 e.** invocations
38230 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e of the same fun
38240 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ction..**.** ^Th
38250 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 e sqlite3_get_au
38260 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 xdata() interfac
38270 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e e returns a poin
38280 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 ter to the metad
38290 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 ata.** associate
382a0 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 d by the sqlite3
382b0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 _set_auxdata() f
382c0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 unction with the
382d0 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a Nth argument.**
382e0 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 value to the ap
382f0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
38300 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 d function. ^If
38310 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 74 61 there is no meta
38320 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 data.** associat
38330 65 64 20 77 69 74 68 20 74 68 65 20 66 75 6e 63 ed with the func
38340 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2c 20 74 tion argument, t
38350 68 69 73 20 73 71 6c 69 74 65 33 5f 67 65 74 5f his sqlite3_get_
38360 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 auxdata() interf
38370 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 ace.** returns a
38380 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a NULL pointer..*
38390 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
383a0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 3_set_auxdata(C,
383b0 4e 2c 50 2c 58 29 20 69 6e 74 65 72 66 61 63 65 N,P,X) interface
383c0 20 73 61 76 65 73 20 50 20 61 73 20 6d 65 74 61 saves P as meta
383d0 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 data for the N-t
383e0 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 h.** argument of
383f0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
38400 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
38410 6e 2e 20 20 5e 53 75 62 73 65 71 75 65 6e 74 0a n. ^Subsequent.
38420 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 ** calls to sqli
38430 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 te3_get_auxdata(
38440 43 2c 4e 29 20 72 65 74 75 72 6e 20 50 20 66 72 C,N) return P fr
38450 6f 6d 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 om the most rece
38460 6e 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 nt.** sqlite3_se
38470 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c t_auxdata(C,N,P,
38480 58 29 20 63 61 6c 6c 20 69 66 20 74 68 65 20 6d X) call if the m
38490 65 74 61 64 61 74 61 20 69 73 20 73 74 69 6c 6c etadata is still
384a0 20 76 61 6c 69 64 20 6f 72 0a 2a 2a 20 4e 55 4c valid or.** NUL
384b0 4c 20 69 66 20 74 68 65 20 6d 65 74 61 64 61 74 L if the metadat
384c0 61 20 68 61 73 20 62 65 65 6e 20 64 69 73 63 61 a has been disca
384d0 72 64 65 64 2e 0a 2a 2a 20 5e 41 66 74 65 72 20 rded..** ^After
384e0 65 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c each call to sql
384f0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 ite3_set_auxdata
38500 28 43 2c 4e 2c 50 2c 58 29 20 77 68 65 72 65 20 (C,N,P,X) where
38510 58 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a X is not NULL,.*
38520 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e * SQLite will in
38530 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 voke the destruc
38540 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 58 20 77 tor function X w
38550 69 74 68 20 70 61 72 61 6d 65 74 65 72 20 50 20 ith parameter P
38560 65 78 61 63 74 6c 79 0a 2a 2a 20 6f 6e 63 65 2c exactly.** once,
38570 20 77 68 65 6e 20 74 68 65 20 6d 65 74 61 64 61 when the metada
38580 74 61 20 69 73 20 64 69 73 63 61 72 64 65 64 2e ta is discarded.
38590 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 .** SQLite is fr
385a0 65 65 20 74 6f 20 64 69 73 63 61 72 64 20 74 68 ee to discard th
385b0 65 20 6d 65 74 61 64 61 74 61 20 61 74 20 61 6e e metadata at an
385c0 79 20 74 69 6d 65 2c 20 69 6e 63 6c 75 64 69 6e y time, includin
385d0 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 g: <ul>.** <li>
385e0 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 when the corresp
385f0 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 onding function
38600 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 parameter change
38610 73 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 s, or.** <li> wh
38620 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 en [sqlite3_rese
38630 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 t()] or [sqlite3
38640 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 _finalize()] is
38650 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a called for the.*
38660 2a 20 20 20 20 20 20 53 51 4c 20 73 74 61 74 65 * SQL state
38670 6d 65 6e 74 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e ment, or.** <li>
38680 20 77 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 65 when sqlite3_se
38690 74 5f 61 75 78 64 61 74 61 28 29 20 69 73 20 69 t_auxdata() is i
386a0 6e 76 6f 6b 65 64 20 61 67 61 69 6e 20 6f 6e 20 nvoked again on
386b0 74 68 65 20 73 61 6d 65 20 70 61 72 61 6d 65 74 the same paramet
386c0 65 72 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 64 er, or.** <li> d
386d0 75 72 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e uring the origin
386e0 61 6c 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 al sqlite3_set_a
386f0 75 78 64 61 74 61 28 29 20 63 61 6c 6c 20 77 68 uxdata() call wh
38700 65 6e 20 61 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 en a memory .**
38710 20 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 allocation
38720 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 3c 2f error occurs. </
38730 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 ul>)^.**.** Note
38740 20 74 68 65 20 6c 61 73 74 20 62 75 6c 6c 65 74 the last bullet
38750 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 2e 20 in particular.
38760 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 The destructor
38770 58 20 69 6e 20 0a 2a 2a 20 73 71 6c 69 74 65 33 X in .** sqlite3
38780