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 31 31 20 31 38 "2015-09-11 18
3160: 3a 30 35 3a 30 31 20 62 66 63 37 62 38 34 62 37 :05:01 bfc7b84b7
3170: 36 36 38 36 30 64 32 65 34 31 30 37 30 32 62 61 66860d2e410702ba
3180: 37 63 31 31 36 36 64 37 33 32 38 33 30 39 61 22 7c1166d7328309a"
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 69 ader, and thus i
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 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 insure 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 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
12540 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 config() interfa
12550 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 ce is not thread
12560 73 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 safe. The appli
12570 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 cation.** must i
12580 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 nsure that no ot
12590 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 her SQLite inter
125a0 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 faces are invoke
125b0 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 d by other.** th
125c0 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 reads while sqli
125d0 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 te3_config() is
125e0 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 running. Furthe
125f0 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 rmore, sqlite3_c
12600 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f onfig().** may o
12610 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 nly be invoked p
12620 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 rior to library
12630 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 initialization u
12640 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 sing.** [sqlite3
12650 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f _initialize()] o
12660 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e r after shutdown
12670 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 by [sqlite3_shu
12680 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 tdown()]..** ^If
12690 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
126a0 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 ) is called afte
126b0 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 r [sqlite3_initi
126c0 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 alize()] and bef
126d0 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ore.** [sqlite3_
126e0 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e shutdown()] then
126f0 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 it will return
12700 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a SQLITE_MISUSE..*
12710 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c * Note, however,
12720 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 that ^sqlite3_c
12730 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 onfig() can be c
12740 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 alled as part of
12750 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e the.** implemen
12760 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 tation of an app
12770 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
12780 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 [sqlite3_os_ini
12790 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 t()]..**.** The
127a0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 first argument t
127b0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 o sqlite3_config
127c0 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 () is an integer
127d0 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 .** [configurati
127e0 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 on option] that
127f0 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 determines.** wh
12800 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 at property of S
12810 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 QLite is to be c
12820 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 onfigured. Subs
12830 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 equent arguments
12840 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 .** vary dependi
12850 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 ng on the [confi
12860 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d guration option]
12870 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 .** in the first
12880 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a argument..**.**
12890 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 ^When a configu
128a0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 ration option is
128b0 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f set, sqlite3_co
128c0 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b nfig() returns [
128d0 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e SQLITE_OK]..** ^
128e0 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 If the option is
128f0 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 unknown or SQLi
12900 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 te is unable to
12910 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a set the option.*
12920 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 * then this rout
12930 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f ine returns a no
12940 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f n-zero [error co
12950 64 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 de]..*/.SQLITE_A
12960 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 43 44 PI int SQLITE_CD
12970 45 43 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 ECL sqlite3_conf
12980 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f ig(int, ...);../
12990 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
129a0 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73 onfigure databas
129b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a e connections.**
129c0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
129d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
129e0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 e3_db_config() i
129f0 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 nterface is used
12a00 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 to make configu
12a10 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 ration.** change
12a20 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 s to a [database
12a30 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 connection]. T
12a40 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 he interface is
12a50 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 similar to.** [s
12a60 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
12a70 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65 except that the
12a80 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 changes apply t
12a90 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 o a single.** [d
12aa0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
12ab0 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 on] (specified i
12ac0 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 n the first argu
12ad0 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ment)..**.** The
12ae0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
12af0 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 to sqlite3_db_c
12b00 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 onfig(D,V,...)
12b10 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 is the.** [SQLIT
12b20 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 E_DBCONFIG_LOOKA
12b30 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 SIDE | configura
12b40 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 tion verb] - an
12b50 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a integer code .**
12b60 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 that indicates
12b70 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 74 what aspect of t
12b80 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
12b90 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e nection] is bein
12ba0 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a g configured..**
12bb0 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 Subsequent argu
12bc0 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e ments vary depen
12bd0 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 ding on the conf
12be0 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a iguration verb..
12bf0 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 **.** ^Calls to
12c00 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 sqlite3_db_confi
12c10 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 g() return SQLIT
12c20 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 E_OK if and only
12c30 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 if.** the call
12c40 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 is considered su
12c50 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c ccessful..*/.SQL
12c60 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 ITE_API int SQLI
12c70 54 45 5f 43 44 45 43 4c 20 73 71 6c 69 74 65 33 TE_CDECL sqlite3
12c80 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 _db_config(sqlit
12c90 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e e3*, int op, ...
12ca0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
12cb0 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 EF: Memory Alloc
12cc0 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a ation Routines.*
12cd0 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 *.** An instance
12ce0 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 of this object
12cf0 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 defines the inte
12d00 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 rface between SQ
12d10 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d Lite.** and low-
12d20 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c level memory all
12d30 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 ocation routines
12d40 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a ..**.** This obj
12d50 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f ect is used in o
12d60 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e nly one place in
12d70 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 the SQLite inte
12d80 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e rface..** A poin
12d90 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e ter to an instan
12da0 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 ce of this objec
12db0 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e t is the argumen
12dc0 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 t to.** [sqlite3
12dd0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 _config()] when
12de0 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f the configuratio
12df0 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b n option is.** [
12e00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 SQLITE_CONFIG_MA
12e10 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 LLOC] or [SQLITE
12e20 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f _CONFIG_GETMALLO
12e30 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 C]. .** By crea
12e40 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 ting an instance
12e50 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a of this object.
12e60 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 ** and passing i
12e70 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f t to [sqlite3_co
12e80 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f nfig]([SQLITE_CO
12e90 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a NFIG_MALLOC]).**
12ea0 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 during configur
12eb0 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 ation, an applic
12ec0 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 ation can specif
12ed0 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 y an alternative
12ee0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 .** memory alloc
12ef0 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 ation subsystem
12f00 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 for SQLite to us
12f10 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 e for all of its
12f20 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f .** dynamic memo
12f30 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 ry needs..**.**
12f40 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 Note that SQLite
12f50 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65 comes with seve
12f60 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 ral [built-in me
12f70 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d mory allocators]
12f80 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72 .** that are per
12f90 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 fectly adequate
12fa0 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c for the overwhel
12fb0 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 ming majority of
12fc0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a applications.**
12fd0 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f and that this o
12fe0 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 bject is only us
12ff0 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d eful to a tiny m
13000 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 inority of appli
13010 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 cations.** with
13020 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f specialized memo
13030 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 ry allocation re
13040 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 quirements. Thi
13050 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 s object is.** a
13060 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 lso used during
13070 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 testing of SQLit
13080 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 e in order to sp
13090 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 ecify an alterna
130a0 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 tive.** memory a
130b0 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 llocator that si
130c0 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f mulates memory o
130d0 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e ut-of-memory con
130e0 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 ditions in.** or
130f0 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 der to verify th
13100 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 at SQLite recove
13110 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 rs gracefully fr
13120 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 om such.** condi
13130 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 tions..**.** The
13140 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c xMalloc, xReall
13150 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65 oc, and xFree me
13160 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 thods must work
13170 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c like the.** mall
13180 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 oc(), realloc()
13190 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 and free() funct
131a0 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 ions from the st
131b0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 andard C library
131c0 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 ..** ^SQLite gua
131d0 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 rantees that the
131e0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
131f0 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 to.** xRealloc
13200 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75 is always a valu
13210 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20 e returned by a
13220 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 prior call to xR
13230 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 oundup..**.** xS
13240 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 ize should retur
13250 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 n the allocated
13260 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 size of a memory
13270 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 allocation.** p
13280 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e reviously obtain
13290 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 ed from xMalloc
132a0 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 or xRealloc. Th
132b0 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 e allocated size
132c0 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 .** is always at
132d0 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73 least as big as
132e0 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73 the requested s
132f0 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c ize but may be l
13300 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 arger..**.** The
13310 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 xRoundup method
13320 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f returns what wo
13330 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 uld be the alloc
13340 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 ated size of.**
13350 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 a memory allocat
13360 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 ion given a part
13370 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 icular requested
13380 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d size. Most mem
13390 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 ory.** allocator
133a0 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 s round up memor
133b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 y allocations at
133c0 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 least to the ne
133d0 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f xt multiple.** o
133e0 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 f 8. Some alloc
133f0 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 ators round up t
13400 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 o a larger multi
13410 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 ple or to a powe
13420 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 r of 2..** Every
13430 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
13440 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e on request comin
13450 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 g in through [sq
13460 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a lite3_malloc()].
13470 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 ** or [sqlite3_r
13480 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 ealloc()] first
13490 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 calls xRoundup.
134a0 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74 If xRoundup ret
134b0 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 urns 0, .** that
134c0 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 72 causes the corr
134d0 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 esponding memory
134e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 allocation to f
134f0 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 ail..**.** The x
13500 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 Init method init
13510 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f ializes the memo
13520 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 ry allocator. F
13530 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 or example,.** i
13540 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 t might allocate
13550 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 any require mut
13560 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 exes or initiali
13570 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 ze internal data
13580 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 .** structures.
13590 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d The xShutdown m
135a0 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 ethod is invoked
135b0 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 (indirectly) by
135c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 .** [sqlite3_shu
135d0 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f tdown()] and sho
135e0 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 uld deallocate a
135f0 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 ny resources acq
13600 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 uired.** by xIni
13610 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61 t. The pAppData
13620 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 pointer is used
13630 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 as the only par
13640 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e ameter to.** xIn
13650 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e it and xShutdown
13660 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 ..**.** SQLite h
13670 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 olds the [SQLITE
13680 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 _MUTEX_STATIC_MA
13690 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e STER] mutex when
136a0 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 it invokes.** t
136b0 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c he xInit method,
136c0 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 so the xInit me
136d0 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 thod need not be
136e0 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 threadsafe. Th
136f0 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d e.** xShutdown m
13700 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 ethod is only ca
13710 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 lled from [sqlit
13720 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 e3_shutdown()] s
13730 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 o it does.** not
13740 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 need to be thre
13750 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 adsafe either.
13760 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 For all other me
13770 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a thods, SQLite.**
13780 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 holds the [SQLI
13790 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f TE_MUTEX_STATIC_
137a0 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f MEM] mutex as lo
137b0 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 ng as the.** [SQ
137c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 LITE_CONFIG_MEMS
137d0 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 TATUS] configura
137e0 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 tion option is t
137f0 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a urned on (which.
13800 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61 ** it is by defa
13810 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20 ult) and so the
13820 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f methods are auto
13830 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c matically serial
13840 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 ized..** However
13850 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e , if [SQLITE_CON
13860 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 FIG_MEMSTATUS] i
13870 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e s disabled, then
13880 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 the other.** me
13890 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 thods must be th
138a0 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65 readsafe or else
138b0 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 make their own
138c0 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 arrangements for
138d0 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f .** serializatio
138e0 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 n..**.** SQLite
138f0 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b will never invok
13900 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 e xInit() more t
13910 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 han once without
13920 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a an intervening.
13930 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 ** call to xShut
13940 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 down()..*/.typed
13950 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
13960 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 3_mem_methods sq
13970 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
13980 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 s;.struct sqlite
13990 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 3_mem_methods {.
139a0 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f void *(*xMallo
139b0 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 c)(int);
139c0 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 /* Memory alloc
139d0 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a ation function *
139e0 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 /. void (*xFree
139f0 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 )(void*);
13a00 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 /* Free a pri
13a10 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f or allocation */
13a20 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c . void *(*xReal
13a30 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b loc)(void*,int);
13a40 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 /* Resize an a
13a50 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 llocation */. i
13a60 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 nt (*xSize)(void
13a70 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a *); /*
13a80 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 Return the size
13a90 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f of an allocatio
13aa0 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f n */. int (*xRo
13ab0 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 undup)(int);
13ac0 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 /* Round u
13ad0 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 p request size t
13ae0 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a o allocation siz
13af0 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e e */. int (*xIn
13b00 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 it)(void*);
13b10 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c /* Initial
13b20 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 ize the memory a
13b30 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f llocator */. vo
13b40 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 id (*xShutdown)(
13b50 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 void*); /*
13b60 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 Deinitialize the
13b70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
13b80 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 r */. void *pAp
13b90 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 pData;
13ba0 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e /* Argumen
13bb0 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 t to xInit() and
13bc0 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a xShutdown() */.
13bd0 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 };../*.** CAPI3R
13be0 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f EF: Configuratio
13bf0 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 n Options.** KEY
13c00 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 WORDS: {configur
13c10 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a ation option}.**
13c20 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 .** These consta
13c30 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 nts are the avai
13c40 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f lable integer co
13c50 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
13c60 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 ons that.** can
13c70 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 be passed as the
13c80 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
13c90 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
13ca0 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 config()] interf
13cb0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 ace..**.** New c
13cc0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
13cd0 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 ions may be adde
13ce0 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 d in future rele
13cf0 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a ases of SQLite..
13d00 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 ** Existing conf
13d10 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
13d20 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f s might be disco
13d30 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 ntinued. Applic
13d40 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 ations.** should
13d50 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 check the retur
13d60 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c n code from [sql
13d70 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 ite3_config()] t
13d80 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 o make sure that
13d90 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 .** the call wor
13da0 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 ked. The [sqlit
13db0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 e3_config()] int
13dc0 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 erface will retu
13dd0 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f rn a.** non-zero
13de0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 [error code] if
13df0 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 a discontinued
13e00 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 or unsupported c
13e10 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
13e20 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 ion.** is invoke
13e30 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a d..**.** <dl>.**
13e40 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
13e50 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 _SINGLETHREAD]]
13e60 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
13e70 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f G_SINGLETHREAD</
13e80 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 dt>.** <dd>There
13e90 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 are no argument
13ea0 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e s to this option
13eb0 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 . ^This option
13ec0 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 sets the.** [thr
13ed0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 eading mode] to
13ee0 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 Single-thread.
13ef0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 In other words,
13f00 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 it disables.** a
13f10 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 ll mutexing and
13f20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f puts SQLite into
13f30 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 a mode where it
13f40 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 can only be use
13f50 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 d.** by a single
13f60 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 thread. ^If S
13f70 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 QLite is compile
13f80 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 d with.** the [S
13f90 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
13fa0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 | SQLITE_THREAD
13fb0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d SAFE=0] compile-
13fc0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e time option then
13fd0 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f .** it is not po
13fe0 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 ssible to change
13ff0 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 the [threading
14000 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 mode] from its d
14010 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 efault.** value
14020 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 of Single-thread
14030 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 and so [sqlite3
14040 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 _config()] will
14050 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 return .** [SQLI
14060 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c TE_ERROR] if cal
14070 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c led with the SQL
14080 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c ITE_CONFIG_SINGL
14090 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 ETHREAD.** confi
140a0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e guration option.
140b0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
140c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 LITE_CONFIG_MULT
140d0 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 ITHREAD]] <dt>SQ
140e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 LITE_CONFIG_MULT
140f0 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 ITHREAD</dt>.**
14100 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f <dd>There are no
14110 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 arguments to th
14120 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 is option. ^Thi
14130 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 s option sets th
14140 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 e.** [threading
14150 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 mode] to Multi-t
14160 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 hread. In other
14170 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 words, it disab
14180 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 les.** mutexing
14190 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e on [database con
141a0 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 nection] and [pr
141b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
141c0 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 ] objects..** Th
141d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 e application is
141e0 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 responsible for
141f0 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 serializing acc
14200 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 ess to.** [datab
14210 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d ase connections]
14220 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 and [prepared s
14230 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 tatements]. But
14240 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a other mutexes.*
14250 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f * are enabled so
14260 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c that SQLite wil
14270 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 l be safe to use
14280 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 in a multi-thre
14290 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d aded.** environm
142a0 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e ent as long as n
142b0 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 o two threads at
142c0 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 tempt to use the
142d0 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 same.** [databa
142e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 se connection] a
142f0 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e t the same time.
14300 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 ^If SQLite is
14310 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a compiled with.**
14320 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
14330 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 EADSAFE | SQLITE
14340 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 _THREADSAFE=0] c
14350 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
14360 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 on then.** it is
14370 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f not possible to
14380 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 set the Multi-t
14390 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 hread [threading
143a0 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 mode] and.** [s
143b0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
143c0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 will return [SQ
143d0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 LITE_ERROR] if c
143e0 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a alled with the.*
143f0 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f * SQLITE_CONFIG_
14400 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66 MULTITHREAD conf
14410 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
14420 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 .</dd>.**.** [[S
14430 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 QLITE_CONFIG_SER
14440 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 IALIZED]] <dt>SQ
14450 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 LITE_CONFIG_SERI
14460 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c ALIZED</dt>.** <
14470 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 dd>There are no
14480 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 arguments to thi
14490 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 s option. ^This
144a0 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 option sets the
144b0 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d .** [threading m
144c0 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a ode] to Serializ
144d0 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 ed. In other wor
144e0 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 ds, this option
144f0 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d enables.** all m
14500 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 utexes including
14510 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a the recursive.*
14520 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 * mutexes on [da
14530 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
14540 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 n] and [prepared
14550 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 statement] obje
14560 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 cts..** In this
14570 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74 mode (which is t
14580 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 he default when
14590 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
145a0 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 ed with.** [SQLI
145b0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d TE_THREADSAFE=1]
145c0 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 ) the SQLite lib
145d0 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 rary will itself
145e0 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 serialize acces
145f0 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 s.** to [databas
14600 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 e connections] a
14610 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 nd [prepared sta
14620 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 tements] so that
14630 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 the.** applicat
14640 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 ion is free to u
14650 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 se the same [dat
14660 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
14670 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 ] or the.** same
14680 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
14690 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 ment] in differe
146a0 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68 nt threads at th
146b0 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 e same time..**
146c0 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f ^If SQLite is co
146d0 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 mpiled with.** t
146e0 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 he [SQLITE_THREA
146f0 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 DSAFE | SQLITE_T
14700 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d HREADSAFE=0] com
14710 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
14720 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e then.** it is n
14730 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 ot possible to s
14740 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65 et the Serialize
14750 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 d [threading mod
14760 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 e] and.** [sqlit
14770 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c e3_config()] wil
14780 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 l return [SQLITE
14790 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 _ERROR] if calle
147a0 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 d with the.** SQ
147b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 LITE_CONFIG_SERI
147c0 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 ALIZED configura
147d0 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 tion option.</dd
147e0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
147f0 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d _CONFIG_MALLOC]]
14800 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
14810 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a IG_MALLOC</dt>.*
14820 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c * <dd> ^(The SQL
14830 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f ITE_CONFIG_MALLO
14840 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 C option takes a
14850 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 single argument
14860 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 which is .** a
14870 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e pointer to an in
14880 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 stance of the [s
14890 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
148a0 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a ds] structure..*
148b0 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 * The argument s
148c0 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 pecifies.** alte
148d0 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 rnative low-leve
148e0 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 l memory allocat
148f0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 ion routines to
14900 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 be used in place
14910 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 of.** the memor
14920 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 y allocation rou
14930 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f tines built into
14940 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 SQLite.)^ ^SQLi
14950 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 te makes.** its
14960 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 own private copy
14970 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 of the content
14980 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
14990 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 mem_methods] str
149a0 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 ucture.** before
149b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f the [sqlite3_co
149c0 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 nfig()] call ret
149d0 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a urns.</dd>.**.**
149e0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
149f0 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 _GETMALLOC]] <dt
14a00 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 >SQLITE_CONFIG_G
14a10 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a ETMALLOC</dt>.**
14a20 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 <dd> ^(The SQLI
14a30 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c TE_CONFIG_GETMAL
14a40 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 LOC option takes
14a50 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 a single argume
14a60 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 nt which.** is a
14a70 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
14a80 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b nstance of the [
14a90 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
14aa0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a ods] structure..
14ab0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f ** The [sqlite3_
14ac0 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 mem_methods].**
14ad0 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c structure is fil
14ae0 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 led with the cur
14af0 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d rently defined m
14b00 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
14b10 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 routines.)^.**
14b20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 This option can
14b30 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c be used to overl
14b40 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 oad the default
14b50 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
14b60 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 n.** routines wi
14b70 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61 th a wrapper tha
14b80 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 t simulations me
14b90 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
14ba0 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 failure or.** tr
14bb0 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 acks memory usag
14bc0 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 e, for example.
14bd0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
14be0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 LITE_CONFIG_MEMS
14bf0 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 TATUS]] <dt>SQLI
14c00 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 TE_CONFIG_MEMSTA
14c10 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e TUS</dt>.** <dd>
14c20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e ^The SQLITE_CON
14c30 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70 FIG_MEMSTATUS op
14c40 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c tion takes singl
14c50 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 e argument of ty
14c60 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72 pe int,.** inter
14c70 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c preted as a bool
14c80 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c ean, which enabl
14c90 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 es or disables t
14ca0 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 he collection of
14cb0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 .** memory alloc
14cc0 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 ation statistics
14cd0 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 . ^(When memory
14ce0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 allocation stati
14cf0 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 69 73 stics are.** dis
14d00 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f abled, the follo
14d10 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 wing SQLite inte
14d20 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f rfaces become no
14d30 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a n-operational:.*
14d40 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c * <ul>.** <l
14d50 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f i> [sqlite3_memo
14d60 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 ry_used()].**
14d70 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 <li> [sqlite3_me
14d80 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 mory_highwater()
14d90 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c ].** <li> [sql
14da0 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c ite3_soft_heap_l
14db0 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c imit64()].** <
14dc0 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 li> [sqlite3_sta
14dd0 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f tus64()].** </
14de0 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 ul>)^.** ^Memory
14df0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 allocation stat
14e00 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c istics are enabl
14e10 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e ed by default un
14e20 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a less SQLite is.*
14e30 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 * compiled with
14e40 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f [SQLITE_DEFAULT_
14e50 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 MEMSTATUS]=0 in
14e60 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 which case memor
14e70 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 y.** allocation
14e80 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 statistics are d
14e90 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 isabled by defau
14ea0 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a lt..** </dd>.**.
14eb0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
14ec0 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 IG_SCRATCH]] <dt
14ed0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 >SQLITE_CONFIG_S
14ee0 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c CRATCH</dt>.** <
14ef0 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f dd> ^The SQLITE_
14f00 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 6f CONFIG_SCRATCH o
14f10 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 ption specifies
14f20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 a static memory
14f30 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 53 buffer.** that S
14f40 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f QLite can use fo
14f50 72 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 r scratch memory
14f60 2e 20 20 5e 28 54 68 65 72 65 20 61 72 65 20 74 . ^(There are t
14f70 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a hree arguments.*
14f80 2a 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 * to SQLITE_CONF
14f90 49 47 5f 53 43 52 41 54 43 48 3a 20 20 41 20 70 IG_SCRATCH: A p
14fa0 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65 ointer an 8-byte
14fb0 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f .** aligned memo
14fc0 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 ry buffer from w
14fd0 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63 68 hich the scratch
14fe0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c allocations wil
14ff0 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 l be.** drawn, t
15000 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 he size of each
15010 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 scratch allocati
15020 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 on (sz),.** and
15030 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 the maximum numb
15040 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c er of scratch al
15050 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 29 5e locations (N).)^
15060 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 .** The first ar
15070 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 gument must be a
15080 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 pointer to an 8
15090 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 -byte aligned bu
150a0 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 ffer.** of at le
150b0 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f ast sz*N bytes o
150c0 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 f memory..** ^SQ
150d0 4c 69 74 65 20 77 69 6c 6c 20 6e 6f 74 20 75 73 Lite will not us
150e0 65 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 e more than one
150f0 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20 scratch buffers
15100 70 65 72 20 74 68 72 65 61 64 2e 0a 2a 2a 20 5e per thread..** ^
15110 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 SQLite will neve
15120 72 20 72 65 71 75 65 73 74 20 61 20 73 63 72 61 r request a scra
15130 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74 20 tch buffer that
15140 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a is more than 6.*
15150 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 * times the data
15160 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e 0a base page size..
15170 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 ** ^If SQLite ne
15180 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 74 69 eds needs additi
15190 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 onal.** scratch
151a0 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 memory beyond wh
151b0 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 at is provided b
151c0 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 y this configura
151d0 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 tion option, the
151e0 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d n .** [sqlite3_m
151f0 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 alloc()] will be
15200 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 used to obtain
15210 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 the memory neede
15220 64 2e 3c 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20 74 d.<p>.** ^When t
15230 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 70 he application p
15240 72 6f 76 69 64 65 73 20 61 6e 79 20 61 6d 6f 75 rovides any amou
15250 6e 74 20 6f 66 20 73 63 72 61 74 63 68 20 6d 65 nt of scratch me
15260 6d 6f 72 79 20 75 73 69 6e 67 0a 2a 2a 20 53 51 mory using.** SQ
15270 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 LITE_CONFIG_SCRA
15280 54 43 48 2c 20 53 51 4c 69 74 65 20 61 76 6f 69 TCH, SQLite avoi
15290 64 73 20 75 6e 6e 65 63 65 73 73 61 72 79 20 6c ds unnecessary l
152a0 61 72 67 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 arge.** [sqlite3
152b0 5f 6d 61 6c 6c 6f 63 7c 68 65 61 70 20 61 6c 6c _malloc|heap all
152c0 6f 63 61 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 ocations]..** Th
152d0 69 73 20 63 61 6e 20 68 65 6c 70 20 5b 52 6f 62 is can help [Rob
152e0 73 6f 6e 20 70 72 6f 6f 66 7c 70 72 65 76 65 6e son proof|preven
152f0 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 t memory allocat
15300 69 6f 6e 20 66 61 69 6c 75 72 65 73 5d 20 64 75 ion failures] du
15310 65 20 74 6f 20 68 65 61 70 0a 2a 2a 20 66 72 61 e to heap.** fra
15320 67 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 20 6c 6f gmentation in lo
15330 77 2d 6d 65 6d 6f 72 79 20 65 6d 62 65 64 64 65 w-memory embedde
15340 64 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c 2f d systems..** </
15350 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
15360 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 TE_CONFIG_PAGECA
15370 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 CHE]] <dt>SQLITE
15380 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 _CONFIG_PAGECACH
15390 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e E</dt>.** <dd> ^
153a0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 The SQLITE_CONFI
153b0 47 5f 50 41 47 45 43 41 43 48 45 20 6f 70 74 69 G_PAGECACHE opti
153c0 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 on specifies a s
153d0 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 tatic memory buf
153e0 66 65 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 fer.** that SQLi
153f0 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20 74 te can use for t
15400 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 he database page
15410 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20 cache with the
15420 64 65 66 61 75 6c 74 20 70 61 67 65 0a 2a 2a 20 default page.**
15430 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 cache implementa
15440 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 tion. .** This
15450 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68 configuration sh
15460 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 ould not be used
15470 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 if an applicati
15480 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a on-define page.*
15490 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e * cache implemen
154a0 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 tation is loaded
154b0 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 using the [SQLI
154c0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 TE_CONFIG_PCACHE
154d0 32 5d 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 2].** configurat
154e0 69 6f 6e 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 5e ion option..** ^
154f0 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 There are three
15500 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c arguments to SQL
15510 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 ITE_CONFIG_PAGEC
15520 41 43 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 ACHE: A pointer
15530 74 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 to.** 8-byte ali
15540 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 gned.** memory,
15550 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 the size of each
15560 20 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a page buffer (sz
15570 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 ), and the numbe
15580 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a r of pages (N)..
15590 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 ** The sz argume
155a0 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 nt should be the
155b0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 size of the lar
155c0 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 gest database pa
155d0 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f ge.** (a power o
155e0 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 f two between 51
155f0 32 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75 2 and 65536) plu
15600 73 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74 s some extra byt
15610 65 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 es for each.** p
15620 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 age header. ^Th
15630 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 e number of extr
15640 61 20 62 79 74 65 73 20 6e 65 65 64 65 64 20 62 a bytes needed b
15650 79 20 74 68 65 20 70 61 67 65 20 68 65 61 64 65 y the page heade
15660 72 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 r.** can be dete
15670 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 rmined using the
15680 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
15690 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 20 6f 70 PCACHE_HDRSZ] op
156a0 74 69 6f 6e 20 0a 2a 2a 20 74 6f 20 5b 73 71 6c tion .** to [sql
156b0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a ite3_config()]..
156c0 2a 2a 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 ** ^It is harmle
156d0 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 ss, apart from t
156e0 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 he wasted memory
156f0 2c 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 7a 20 ,.** for the sz
15700 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 parameter to be
15710 6c 61 72 67 65 72 20 74 68 61 6e 20 6e 65 63 65 larger than nece
15720 73 73 61 72 79 2e 20 20 54 68 65 20 66 69 72 73 ssary. The firs
15730 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 t.** argument sh
15740 6f 75 6c 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 ould pointer to
15750 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 an 8-byte aligne
15760 64 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 d block of memor
15770 79 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 74 20 y that.** is at
15780 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 least sz*N bytes
15790 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 6f 74 68 65 of memory, othe
157a0 72 77 69 73 65 20 73 75 62 73 65 71 75 65 6e 74 rwise subsequent
157b0 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 behavior is.**
157c0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 53 undefined..** ^S
157d0 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 QLite will use t
157e0 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 he memory provid
157f0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 ed by the first
15800 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 argument to sati
15810 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 sfy its.** memor
15820 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 y needs for the
15830 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 first N pages th
15840 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 at it adds to ca
15850 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69 che. ^If additi
15860 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 onal.** page cac
15870 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 he memory is nee
15880 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 ded beyond what
15890 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 is provided by t
158a0 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e his option, then
158b0 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 .** SQLite goes
158c0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c to [sqlite3_mall
158d0 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 oc()] for the ad
158e0 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 ditional storage
158f0 20 73 70 61 63 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a space.</dd>.**.
15900 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
15910 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 IG_HEAP]] <dt>SQ
15920 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 LITE_CONFIG_HEAP
15930 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 </dt>.** <dd> ^T
15940 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
15950 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 _HEAP option spe
15960 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 cifies a static
15970 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a memory buffer .*
15980 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 * that SQLite wi
15990 6c 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f ll use for all o
159a0 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 f its dynamic me
159b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
159c0 6e 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 needs.** beyond
159d0 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66 those provided f
159e0 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f or by [SQLITE_CO
159f0 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e NFIG_SCRATCH] an
15a00 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e d.** [SQLITE_CON
15a10 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a FIG_PAGECACHE]..
15a20 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 ** ^The SQLITE_C
15a30 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f ONFIG_HEAP optio
15a40 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 n is only availa
15a50 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 ble if SQLite is
15a60 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 compiled.** wit
15a70 68 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 h either [SQLITE
15a80 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d _ENABLE_MEMSYS3]
15a90 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 or [SQLITE_ENAB
15aa0 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 LE_MEMSYS5] and
15ab0 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 returns.** [SQLI
15ac0 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 TE_ERROR] if inv
15ad0 6f 6b 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a oked otherwise..
15ae0 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 ** ^There are th
15af0 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f ree arguments to
15b00 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 SQLITE_CONFIG_H
15b10 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 EAP:.** An 8-byt
15b20 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 e aligned pointe
15b30 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c r to the memory,
15b40 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f .** the number o
15b50 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d f bytes in the m
15b60 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e emory buffer, an
15b70 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c d the minimum al
15b80 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a location size..*
15b90 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 * ^If the first
15ba0 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d pointer (the mem
15bb0 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 ory pointer) is
15bc0 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 NULL, then SQLit
15bd0 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 e reverts.** to
15be0 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c using its defaul
15bf0 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 t memory allocat
15c00 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d or (the system m
15c10 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e alloc() implemen
15c20 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f tation),.** undo
15c30 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e ing any prior in
15c40 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c vocation of [SQL
15c50 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f ITE_CONFIG_MALLO
15c60 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 C]. ^If the.**
15c70 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 memory pointer i
15c80 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 s not NULL then
15c90 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 the alternative
15ca0 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 memory.** alloca
15cb0 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 tor is engaged t
15cc0 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 o handle all of
15cd0 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 SQLites memory a
15ce0 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e llocation needs.
15cf0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f .** The first po
15d00 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 inter (the memor
15d10 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 y pointer) must
15d20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e be aligned to an
15d30 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 8-byte.** bound
15d40 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e ary or subsequen
15d50 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 t behavior of SQ
15d60 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 Lite will be und
15d70 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d efined..** The m
15d80 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f inimum allocatio
15d90 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 n size is capped
15da0 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f at 2**12. Reaso
15db0 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 nable values.**
15dc0 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 for the minimum
15dd0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 allocation size
15de0 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 are 2**5 through
15df0 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2**8.</dd>.**.*
15e00 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
15e10 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 G_MUTEX]] <dt>SQ
15e20 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 LITE_CONFIG_MUTE
15e30 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e X</dt>.** <dd> ^
15e40 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 (The SQLITE_CONF
15e50 49 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 IG_MUTEX option
15e60 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 takes a single a
15e70 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 rgument which is
15e80 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f a.** pointer to
15e90 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 an instance of
15ea0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 the [sqlite3_mut
15eb0 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 ex_methods] stru
15ec0 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 cture..** The ar
15ed0 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 gument specifies
15ee0 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 alternative low
15ef0 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 -level mutex rou
15f00 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 tines to be used
15f10 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65 .** in place the
15f20 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 mutex routines
15f30 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 built into SQLit
15f40 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 e.)^ ^SQLite ma
15f50 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a kes a copy of.**
15f60 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 the content of
15f70 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 the [sqlite3_mut
15f80 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 ex_methods] stru
15f90 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 cture before the
15fa0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c call to.** [sql
15fb0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 ite3_config()] r
15fc0 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 eturns. ^If SQLi
15fd0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
15fe0 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 ith.** the [SQLI
15ff0 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 TE_THREADSAFE |
16000 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
16010 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d E=0] compile-tim
16020 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a e option then.**
16030 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 the entire mute
16040 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 xing subsystem i
16050 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 s omitted from t
16060 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e he build and hen
16070 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b ce calls to.** [
16080 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
16090 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 ] with the SQLIT
160a0 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 E_CONFIG_MUTEX c
160b0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
160c0 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 ion will.** retu
160d0 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 rn [SQLITE_ERROR
160e0 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b ].</dd>.**.** [[
160f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
16100 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c TMUTEX]] <dt>SQL
16110 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 ITE_CONFIG_GETMU
16120 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e TEX</dt>.** <dd>
16130 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f ^(The SQLITE_CO
16140 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 NFIG_GETMUTEX op
16150 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e tion takes a sin
16160 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 gle argument whi
16170 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 ch.** is a point
16180 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 er to an instanc
16190 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 e of the [sqlite
161a0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 3_mutex_methods]
161b0 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 structure. The
161c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 .** [sqlite3_mut
161d0 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 ex_methods].** s
161e0 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c tructure is fill
161f0 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 ed with the curr
16200 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 ently defined mu
16210 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a tex routines.)^.
16220 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 ** This option c
16230 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 an be used to ov
16240 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 erload the defau
16250 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 lt mutex allocat
16260 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 ion.** routines
16270 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75 with a wrapper u
16280 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 sed to track mut
16290 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 ex usage for per
162a0 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 formance.** prof
162b0 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 iling or testing
162c0 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 , for example.
162d0 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 ^If SQLite is c
162e0 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 ompiled with.**
162f0 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 the [SQLITE_THRE
16300 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f ADSAFE | SQLITE_
16310 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f THREADSAFE=0] co
16320 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
16330 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e n then.** the en
16340 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 tire mutexing su
16350 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 bsystem is omitt
16360 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c ed from the buil
16370 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c d and hence call
16380 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 s to.** [sqlite3
16390 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 _config()] with
163a0 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 the SQLITE_CONFI
163b0 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 G_GETMUTEX confi
163c0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 guration option
163d0 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b will.** return [
163e0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f SQLITE_ERROR].</
163f0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
16400 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 TE_CONFIG_LOOKAS
16410 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 IDE]] <dt>SQLITE
16420 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 _CONFIG_LOOKASID
16430 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e E</dt>.** <dd> ^
16440 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 (The SQLITE_CONF
16450 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 IG_LOOKASIDE opt
16460 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 ion takes two ar
16470 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 guments that det
16480 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 ermine.** the de
16490 66 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f fault size of lo
164a0 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f okaside memory o
164b0 6e 20 65 61 63 68 20 5b 64 61 74 61 62 61 73 65 n each [database
164c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a connection]..**
164d0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
164e0 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 ent is the.** si
164f0 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 ze of each looka
16500 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 side buffer slot
16510 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 and the second
16520 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 is the number of
16530 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 .** slots alloca
16540 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 ted to each data
16550 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e base connection.
16560 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e )^ ^(SQLITE_CON
16570 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a FIG_LOOKASIDE.**
16580 20 73 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66 sets the <i>def
16590 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 ault</i> lookasi
165a0 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 de size. The [SQ
165b0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f LITE_DBCONFIG_LO
165c0 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 OKASIDE].** opti
165d0 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 on to [sqlite3_d
165e0 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 b_config()] can
165f0 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 be used to chang
16600 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a e the lookaside.
16610 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ** configuration
16620 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 on individual c
16630 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f onnections.)^ </
16640 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
16650 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 TE_CONFIG_PCACHE
16660 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 2]] <dt>SQLITE_C
16670 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 ONFIG_PCACHE2</d
16680 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 t>.** <dd> ^(The
16690 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 SQLITE_CONFIG_P
166a0 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 CACHE2 option ta
166b0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 kes a single arg
166c0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a ument which is .
166d0 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ** a pointer to
166e0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 an [sqlite3_pcac
166f0 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a he_methods2] obj
16700 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 ect. This objec
16710 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 t specifies.** t
16720 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 he interface to
16730 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 a custom page ca
16740 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 che implementati
16750 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 on.)^.** ^SQLite
16760 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 makes a copy of
16770 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 the [sqlite3_pc
16780 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f ache_methods2] o
16790 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a bject.</dd>.**.*
167a0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
167b0 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c G_GETPCACHE2]] <
167c0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
167d0 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e _GETPCACHE2</dt>
167e0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 .** <dd> ^(The S
167f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
16800 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 PCACHE2 option t
16810 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 akes a single ar
16820 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 gument which.**
16830 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
16840 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 an [sqlite3_pcac
16850 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a he_methods2] obj
16860 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 ect. SQLite cop
16870 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 ies of.** the cu
16880 72 72 65 6e 74 20 70 61 67 65 20 63 61 63 68 65 rrent page cache
16890 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
168a0 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 into that object
168b0 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 .)^ </dd>.**.**
168c0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
168d0 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 LOG]] <dt>SQLITE
168e0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e _CONFIG_LOG</dt>
168f0 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c .** <dd> The SQL
16900 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f ITE_CONFIG_LOG o
16910 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f ption is used to
16920 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53 configure the S
16930 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 QLite.** global
16940 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 [error log]..**
16950 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e (^The SQLITE_CON
16960 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 FIG_LOG option t
16970 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e akes two argumen
16980 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f ts: a pointer to
16990 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 a.** function w
169a0 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 ith a call signa
169b0 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 ture of void(*)(
169c0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 void*,int,const
169d0 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 char*), .** and
169e0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 a pointer to voi
169f0 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 d. ^If the funct
16a00 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e ion pointer is n
16a10 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a ot NULL, it is.*
16a20 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 * invoked by [sq
16a30 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 lite3_log()] to
16a40 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 process each log
16a50 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 ging event. ^If
16a60 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e the.** function
16a70 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c pointer is NULL
16a80 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c , the [sqlite3_l
16a90 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 og()] interface
16aa0 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e becomes a no-op.
16ab0 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f .** ^The void po
16ac0 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68 inter that is th
16ad0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
16ae0 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 t to SQLITE_CONF
16af0 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 IG_LOG is.** pas
16b00 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 sed through as t
16b10 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
16b20 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 er to the applic
16b30 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f ation-defined lo
16b40 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e gger.** function
16b50 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 whenever that f
16b60 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b unction is invok
16b70 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 ed. ^The second
16b80 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a parameter to.**
16b90 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 the logger func
16ba0 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f tion is a copy o
16bb0 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 f the first para
16bc0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 meter to the cor
16bd0 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 responding.** [s
16be0 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 qlite3_log()] ca
16bf0 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 ll and is intend
16c00 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 ed to be a [resu
16c10 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a lt code] or an.*
16c20 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 * [extended resu
16c30 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 lt code]. ^The
16c40 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
16c50 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f passed to the lo
16c60 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d gger is.** log m
16c70 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 essage after for
16c80 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c matting via [sql
16c90 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d ite3_snprintf()]
16ca0 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 ..** The SQLite
16cb0 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 logging interfac
16cc0 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 e is not reentra
16cd0 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 nt; the logger f
16ce0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c unction.** suppl
16cf0 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 ied by the appli
16d00 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 cation must not
16d10 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 invoke any SQLit
16d20 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 e interface..**
16d30 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 In a multi-threa
16d40 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c ded application,
16d50 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
16d60 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a -defined logger.
16d70 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 ** function must
16d80 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 be threadsafe.
16d90 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
16da0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d LITE_CONFIG_URI]
16db0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
16dc0 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e FIG_URI.** <dd>^
16dd0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 (The SQLITE_CONF
16de0 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 IG_URI option ta
16df0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 kes a single arg
16e00 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e ument of type in
16e10 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 t..** If non-zer
16e20 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 o, then URI hand
16e30 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 ling is globally
16e40 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 enabled. If the
16e50 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 parameter is ze
16e60 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 ro,.** then URI
16e70 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 handling is glob
16e80 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e ally disabled.)^
16e90 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e ^If URI handlin
16ea0 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a g is globally.**
16eb0 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 enabled, all fi
16ec0 6c 65 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74 lenames passed t
16ed0 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 o [sqlite3_open(
16ee0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 )], [sqlite3_ope
16ef0 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c n_v2()],.** [sql
16f00 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f ite3_open16()] o
16f10 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 r.** specified a
16f20 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 s part of [ATTAC
16f30 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 H] commands are
16f40 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 interpreted as U
16f50 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a RIs, regardless.
16f60 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 ** of whether or
16f70 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 not the [SQLITE
16f80 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 _OPEN_URI] flag
16f90 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 is set when the
16fa0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e database.** conn
16fb0 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 ection is opened
16fc0 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62 . ^If it is glob
16fd0 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 ally disabled, f
16fe0 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 ilenames are.**
16ff0 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 only interpreted
17000 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20 as URIs if the
17010 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 SQLITE_OPEN_URI
17020 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e flag is set when
17030 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 the.** database
17040 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f connection is o
17050 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61 pened. ^(By defa
17060 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e ult, URI handlin
17070 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a g is globally.**
17080 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 disabled. The d
17090 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 efault value may
170a0 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 be changed by c
170b0 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 ompiling with th
170c0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 e.** [SQLITE_USE
170d0 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 _URI] symbol def
170e0 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b ined.)^.**.** [[
170f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f SQLITE_CONFIG_CO
17100 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 VERING_INDEX_SCA
17110 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 N]] <dt>SQLITE_C
17120 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 ONFIG_COVERING_I
17130 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 NDEX_SCAN.** <dd
17140 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e >^The SQLITE_CON
17150 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 FIG_COVERING_IND
17160 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 EX_SCAN option t
17170 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e akes a single in
17180 74 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e teger.** argumen
17190 74 20 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 t which is inter
171a0 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c preted as a bool
171b0 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 ean in order to
171c0 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c enable or disabl
171d0 65 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 e.** the use of
171e0 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 covering indices
171f0 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 for full table
17200 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 scans in the que
17210 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a ry optimizer..**
17220 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 ^The default se
17230 74 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 tting is determi
17240 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 ned.** by the [S
17250 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 QLITE_ALLOW_COVE
17260 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d RING_INDEX_SCAN]
17270 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
17280 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 tion, or is "on"
17290 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 .** if that comp
172a0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile-time option
172b0 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 is omitted..** T
172c0 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 he ability to di
172d0 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 sable the use of
172e0 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 covering indice
172f0 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 s for full table
17300 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 scans.** is bec
17310 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 ause some incorr
17320 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 ectly coded lega
17330 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 cy applications
17340 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f might malfunctio
17350 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 n.** when the op
17360 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e timization is en
17370 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e abled. Providin
17380 67 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f g the ability to
17390 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20 .** disable the
173a0 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c optimization all
173b0 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 ows the older, b
173c0 75 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e uggy application
173d0 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a code to work.**
173e0 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20 without change
173f0 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20 even with newer
17400 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
17410 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 te..**.** [[SQLI
17420 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 TE_CONFIG_PCACHE
17430 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ]] [[SQLITE_CONF
17440 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a IG_GETPCACHE]].*
17450 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
17460 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 FIG_PCACHE and S
17470 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
17480 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 PCACHE.** <dd> T
17490 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 hese options are
174a0 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 obsolete and sh
174b0 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 ould not be used
174c0 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a by new code..**
174d0 20 54 68 65 79 20 61 72 65 20 72 65 74 61 69 6e They are retain
174e0 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 ed for backwards
174f0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 compatibility b
17500 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 ut are now no-op
17510 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a s..** </dd>.**.*
17520 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
17530 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 G_SQLLOG]].** <d
17540 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
17550 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 SQLLOG.** <dd>Th
17560 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c is option is onl
17570 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73 y available if s
17580 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 qlite is compile
17590 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 d with the.** [S
175a0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c QLITE_ENABLE_SQL
175b0 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 LOG] pre-process
175c0 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 or macro defined
175d0 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 . The first argu
175e0 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 ment should.** b
175f0 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 e a pointer to a
17600 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 function of typ
17610 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c e void(*)(void*,
17620 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 sqlite3*,const c
17630 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 har*, int)..** T
17640 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 he second should
17650 20 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69 be of type (voi
17660 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 d*). The callbac
17670 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 k is invoked by
17680 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 the library.** i
17690 6e 20 74 68 72 65 65 20 73 65 70 61 72 61 74 65 n three separate
176a0 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 circumstances,
176b0 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 identified by th
176c0 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 e value passed a
176d0 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 s the.** fourth
176e0 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68 parameter. If th
176f0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
17700 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 er is 0, then th
17710 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
17720 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 ction.** passed
17730 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 as the second ar
17740 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20 gument has just
17750 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 been opened. The
17760 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a third argument.
17770 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 ** points to a b
17780 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 uffer containing
17790 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
177a0 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 main database f
177b0 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 ile. If the.** f
177c0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
177d0 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53 is 1, then the S
177e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 QL statement tha
177f0 74 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 t the third para
17800 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 meter.** points
17810 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e to has just been
17820 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 executed. Or, i
17830 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 f the fourth par
17840 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68 65 ameter is 2, the
17850 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 n.** the connect
17860 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64 ion being passed
17870 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 as the second p
17880 61 72 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e arameter is bein
17890 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a g closed. The.**
178a0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
178b0 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 is passed NULL
178c0 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20 41 In this case. A
178d0 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 n example of usi
178e0 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 ng this.** confi
178f0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 guration option
17900 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74 can be seen in t
17910 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e he "test_sqllog.
17920 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69 c" source file i
17930 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 n.** the canonic
17940 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 al SQLite source
17950 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a tree.</dd>.**.*
17960 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
17970 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a G_MMAP_SIZE]].**
17980 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
17990 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 IG_MMAP_SIZE.**
179a0 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dd>^SQLITE_CONF
179b0 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b IG_MMAP_SIZE tak
179c0 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e es two 64-bit in
179d0 74 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69 teger (sqlite3_i
179e0 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 nt64) values.**
179f0 74 68 61 74 20 61 72 65 20 74 68 65 20 64 65 66 that are the def
17a00 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c ault mmap size l
17a10 69 6d 69 74 20 28 74 68 65 20 64 65 66 61 75 6c imit (the defaul
17a20 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a t setting for.**
17a30 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 [PRAGMA mmap_si
17a40 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78 ze]) and the max
17a50 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 imum allowed mma
17a60 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a p size limit..**
17a70 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 ^The default se
17a80 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 tting can be ove
17a90 72 72 69 64 64 65 6e 20 62 79 20 65 61 63 68 20 rridden by each
17aa0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
17ab0 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 ion using.** eit
17ac0 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20 her the [PRAGMA
17ad0 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 mmap_size] comma
17ae0 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20 nd, or by using
17af0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 the.** [SQLITE_F
17b00 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 CNTL_MMAP_SIZE]
17b10 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e file control. ^
17b20 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c (The maximum all
17b30 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a owed mmap size.*
17b40 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 * will be silent
17b50 6c 79 20 74 72 75 6e 63 61 74 65 64 20 69 66 20 ly truncated if
17b60 6e 65 63 65 73 73 61 72 79 20 73 6f 20 74 68 61 necessary so tha
17b70 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 t it does not ex
17b80 63 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 ceed the.** comp
17b90 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d ile-time maximum
17ba0 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 mmap size set b
17bb0 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 y the.** [SQLITE
17bc0 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 _MAX_MMAP_SIZE]
17bd0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
17be0 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 ion.)^.** ^If ei
17bf0 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f ther argument to
17c00 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 this option is
17c10 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 negative, then t
17c20 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a hat argument is.
17c30 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 ** changed to it
17c40 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 s compile-time d
17c50 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b efault..**.** [[
17c60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 SQLITE_CONFIG_WI
17c70 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a N32_HEAPSIZE]].*
17c80 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
17c90 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 FIG_WIN32_HEAPSI
17ca0 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 ZE.** <dd>^The S
17cb0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e QLITE_CONFIG_WIN
17cc0 33 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69 32_HEAPSIZE opti
17cd0 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c on is only avail
17ce0 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 able if SQLite i
17cf0 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f s.** compiled fo
17d00 72 20 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74 r Windows with t
17d10 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 he [SQLITE_WIN32
17d20 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f _MALLOC] pre-pro
17d30 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 cessor macro.**
17d40 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 defined. ^SQLITE
17d50 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 _CONFIG_WIN32_HE
17d60 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33 APSIZE takes a 3
17d70 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 2-bit unsigned i
17d80 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 nteger value.**
17d90 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74 that specifies t
17da0 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 he maximum size
17db0 6f 66 20 74 68 65 20 63 72 65 61 74 65 64 20 68 of the created h
17dc0 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c eap..**.** [[SQL
17dd0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 ITE_CONFIG_PCACH
17de0 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 E_HDRSZ]].** <dt
17df0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 >SQLITE_CONFIG_P
17e00 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c CACHE_HDRSZ.** <
17e10 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 dd>^The SQLITE_C
17e20 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 ONFIG_PCACHE_HDR
17e30 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 SZ option takes
17e40 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 a single paramet
17e50 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 er which.** is a
17e60 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
17e70 6e 74 65 67 65 72 20 61 6e 64 20 77 72 69 74 65 nteger and write
17e80 73 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 s into that inte
17e90 67 65 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f ger the number o
17ea0 66 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 f extra.** bytes
17eb0 20 70 65 72 20 70 61 67 65 20 72 65 71 75 69 72 per page requir
17ec0 65 64 20 66 6f 72 20 65 61 63 68 20 70 61 67 65 ed for each page
17ed0 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 in [SQLITE_CONF
17ee0 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a IG_PAGECACHE]..*
17ef0 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 * The amount of
17f00 65 78 74 72 61 20 73 70 61 63 65 20 72 65 71 75 extra space requ
17f10 69 72 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20 ired can change
17f20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 depending on the
17f30 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 compiler,.** ta
17f40 72 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 rget platform, a
17f50 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f nd SQLite versio
17f60 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 n..**.** [[SQLIT
17f70 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d E_CONFIG_PMASZ]]
17f80 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 .** <dt>SQLITE_C
17f90 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c ONFIG_PMASZ.** <
17fa0 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 dd>^The SQLITE_C
17fb0 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 ONFIG_PMASZ opti
17fc0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
17fd0 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 e parameter whic
17fe0 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 h.** is an unsig
17ff0 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 ned integer and
18000 73 65 74 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 sets the "Minimu
18010 6d 20 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 m PMA Size" for
18020 74 68 65 20 6d 75 6c 74 69 74 68 72 65 61 64 65 the multithreade
18030 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 d.** sorter to t
18040 68 61 74 20 69 6e 74 65 67 65 72 2e 20 20 54 68 hat integer. Th
18050 65 20 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 e default minimu
18060 6d 20 50 4d 41 20 53 69 7a 65 20 69 73 20 73 65 m PMA Size is se
18070 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c t by the.** [SQL
18080 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a ITE_SORTER_PMASZ
18090 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
180a0 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 ption. New thre
180b0 61 64 73 20 61 72 65 20 6c 61 75 6e 63 68 65 64 ads are launched
180c0 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 68 .** to help with
180d0 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 sort operations
180e0 20 77 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 when multithrea
180f0 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 ded sorting.** i
18100 73 20 65 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 s enabled (using
18110 20 74 68 65 20 5b 50 52 41 47 4d 41 20 74 68 72 the [PRAGMA thr
18120 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 eads] command) a
18130 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 nd the amount of
18140 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 content.** to b
18150 65 20 73 6f 72 74 65 64 20 65 78 63 65 65 64 73 e sorted exceeds
18160 20 74 68 65 20 70 61 67 65 20 73 69 7a 65 20 74 the page size t
18170 69 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d imes the minimum
18180 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 of the.** [PRAG
18190 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 MA cache_size] s
181a0 65 74 74 69 6e 67 20 61 6e 64 20 74 68 69 73 20 etting and this
181b0 76 61 6c 75 65 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a value..** </dl>.
181c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
181d0 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 E_CONFIG_SINGLET
181e0 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c HREAD 1 /* nil
181f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
18200 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 TE_CONFIG_MULTIT
18210 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 HREAD 2 /* ni
18220 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c l */.#define SQL
18230 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 ITE_CONFIG_SERIA
18240 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e LIZED 3 /* n
18250 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 il */.#define SQ
18260 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c LITE_CONFIG_MALL
18270 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 OC 4 /*
18280 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
18290 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ods* */.#define
182a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
182b0 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f TMALLOC 5 /
182c0 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 * sqlite3_mem_me
182d0 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e thods* */.#defin
182e0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
182f0 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20 SCRATCH 6
18300 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 /* void*, int s
18310 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 z, int N */.#def
18320 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
18330 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20 G_PAGECACHE
18340 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 7 /* void*, int
18350 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 sz, int N */.#d
18360 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
18370 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 FIG_HEAP
18380 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 8 /* void*, i
18390 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 nt nByte, int mi
183a0 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c n */.#define SQL
183b0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 ITE_CONFIG_MEMST
183c0 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 ATUS 9 /* b
183d0 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e oolean */.#defin
183e0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
183f0 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20 MUTEX 10
18400 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 /* sqlite3_mute
18410 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 x_methods* */.#d
18420 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
18430 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 FIG_GETMUTEX
18440 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 11 /* sqlite3_
18450 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a mutex_methods* *
18460 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 /./* previously
18470 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 SQLITE_CONFIG_CH
18480 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 UNKALLOC 12 whic
18490 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e h is now unused.
184a0 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c */ .#define SQL
184b0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 ITE_CONFIG_LOOKA
184c0 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 SIDE 13 /* i
184d0 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e nt int */.#defin
184e0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
184f0 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20 PCACHE 14
18500 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 /* no-op */.#de
18510 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
18520 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 IG_GETPCACHE
18530 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 15 /* no-op */.
18540 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
18550 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 ONFIG_LOG
18560 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 16 /* xFunc,
18570 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e void* */.#defin
18580 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
18590 55 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20 URI 17
185a0 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 /* int */.#defi
185b0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
185c0 5f 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38 _PCACHE2 18
185d0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 /* sqlite3_pca
185e0 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f che_methods2* */
185f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
18600 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 CONFIG_GETPCACHE
18610 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 2 19 /* sqlit
18620 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 e3_pcache_method
18630 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 s2* */.#define S
18640 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 QLITE_CONFIG_COV
18650 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e ERING_INDEX_SCAN
18660 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 20 /* int */.#
18670 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
18680 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 NFIG_SQLLOG
18690 20 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 21 /* xSqllog
186a0 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 , void* */.#defi
186b0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
186c0 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 _MMAP_SIZE 22
186d0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 /* sqlite3_int
186e0 36 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 64, sqlite3_int6
186f0 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 4 */.#define SQL
18700 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 ITE_CONFIG_WIN32
18710 5f 48 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 _HEAPSIZE 2
18720 33 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 3 /* int nByte
18730 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
18740 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f E_CONFIG_PCACHE_
18750 48 44 52 53 5a 20 20 20 20 20 20 20 20 32 34 20 HDRSZ 24
18760 20 2f 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a /* int *psz */.
18770 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
18780 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 ONFIG_PMASZ
18790 20 20 20 20 20 20 20 20 20 20 32 35 20 20 2f 2a 25 /*
187a0 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 7a unsigned int sz
187b0 50 6d 61 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 Pma */../*.** CA
187c0 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 PI3REF: Database
187d0 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 Connection Conf
187e0 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e iguration Option
187f0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f s.**.** These co
18800 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 nstants are the
18810 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 available intege
18820 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 r configuration
18830 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 options that.**
18840 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 can be passed as
18850 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 the second argu
18860 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c ment to the [sql
18870 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
18880 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a ] interface..**.
18890 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 ** New configura
188a0 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 tion options may
188b0 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 be added in fut
188c0 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 ure releases of
188d0 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 SQLite..** Exist
188e0 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ing configuratio
188f0 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 n options might
18900 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e be discontinued.
18910 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a Applications.*
18920 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 * should check t
18930 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 he return code f
18940 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f rom [sqlite3_db_
18950 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b config()] to mak
18960 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 e sure that.** t
18970 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 he call worked.
18980 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 ^The [sqlite3_d
18990 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 b_config()] inte
189a0 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 rface will retur
189b0 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 n a.** non-zero
189c0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 [error code] if
189d0 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f a discontinued o
189e0 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f r unsupported co
189f0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
18a00 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 on.** is invoked
18a10 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 ..**.** <dl>.**
18a20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e <dt>SQLITE_DBCON
18a30 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 FIG_LOOKASIDE</d
18a40 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 t>.** <dd> ^This
18a50 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 option takes th
18a60 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 ree additional a
18a70 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 rguments that de
18a80 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 termine the .**
18a90 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 [lookaside memor
18aa0 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e y allocator] con
18ab0 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 figuration for t
18ac0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
18ad0 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 nection]..** ^Th
18ae0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
18af0 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72 61 (the third para
18b00 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 meter to [sqlite
18b10 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 3_db_config()] i
18b20 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 s a.** pointer t
18b30 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 o a memory buffe
18b40 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f r to use for loo
18b50 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a kaside memory..*
18b60 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 * ^The first arg
18b70 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 ument after the
18b80 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
18b90 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a LOOKASIDE verb.*
18ba0 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e * may be NULL in
18bb0 20 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 which case SQLi
18bc0 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 te will allocate
18bd0 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 the.** lookasid
18be0 65 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 e buffer itself
18bf0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d using [sqlite3_m
18c00 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 alloc()]. ^The s
18c10 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 econd argument i
18c20 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 s the.** size of
18c30 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 each lookaside
18c40 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 buffer slot. ^T
18c50 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e he third argumen
18c60 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 t is the number
18c70 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 of.** slots. Th
18c80 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 e size of the bu
18c90 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 ffer in the firs
18ca0 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 t argument must
18cb0 62 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a be greater than.
18cc0 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 ** or equal to t
18cd0 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 he product of th
18ce0 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 e second and thi
18cf0 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 rd arguments. T
18d00 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 he buffer.** mus
18d10 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 t be aligned to
18d20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 an 8-byte bounda
18d30 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 ry. ^If the sec
18d40 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a ond argument to.
18d50 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 ** SQLITE_DBCONF
18d60 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 IG_LOOKASIDE is
18d70 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f not a multiple o
18d80 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 f 8, it is inter
18d90 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 nally.** rounded
18da0 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 down to the nex
18db0 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 t smaller multip
18dc0 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 le of 8. ^(The
18dd0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 lookaside memory
18de0 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f .** configuratio
18df0 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 n for a database
18e00 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 connection can
18e10 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 only be changed
18e20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e when that.** con
18e30 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 nection is not c
18e40 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c urrently using l
18e50 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c ookaside memory,
18e60 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 or in other wor
18e70 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 ds.** when the "
18e80 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 current value" r
18e90 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 eturned by.** [s
18ea0 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 qlite3_db_status
18eb0 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ](D,[SQLITE_CONF
18ec0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e IG_LOOKASIDE],..
18ed0 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 .) is zero..** A
18ee0 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 ny attempt to ch
18ef0 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 ange the lookasi
18f00 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 de memory config
18f10 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f uration when loo
18f20 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 kaside.** memory
18f30 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 is in use leave
18f40 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 s the configurat
18f50 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e ion unchanged an
18f60 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 d returns .** [S
18f70 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f QLITE_BUSY].)^</
18f80 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
18f90 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e LITE_DBCONFIG_EN
18fa0 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a ABLE_FKEY</dt>.*
18fb0 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 * <dd> ^This opt
18fc0 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 ion is used to e
18fd0 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 nable or disable
18fe0 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 the enforcement
18ff0 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 of.** [foreign
19000 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d key constraints]
19010 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 . There should
19020 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 be two additiona
19030 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 l arguments..**
19040 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
19050 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 nt is an integer
19060 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 which is 0 to d
19070 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 isable FK enforc
19080 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 ement,.** positi
19090 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 ve to enable FK
190a0 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e enforcement or n
190b0 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 egative to leave
190c0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a FK enforcement.
190d0 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 ** unchanged. T
190e0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
190f0 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 ter is a pointer
19100 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 to an integer i
19110 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 nto which.** is
19120 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 written 0 or 1 t
19130 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 o indicate wheth
19140 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e er FK enforcemen
19150 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a t is off or on.*
19160 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 * following this
19170 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f call. The seco
19180 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 nd parameter may
19190 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 be a NULL point
191a0 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 er, in.** which
191b0 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f case the FK enfo
191c0 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 rcement setting
191d0 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 is not reported
191e0 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a back. </dd>.**.*
191f0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 * <dt>SQLITE_DBC
19200 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 ONFIG_ENABLE_TRI
19210 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 GGER</dt>.** <dd
19220 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 > ^This option i
19230 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 s used to enable
19240 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 or disable [CRE
19250 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 ATE TRIGGER | tr
19260 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 iggers]..** Ther
19270 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 e should be two
19280 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d additional argum
19290 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 ents..** The fir
192a0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 st argument is a
192b0 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 n integer which
192c0 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 is 0 to disable
192d0 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 triggers,.** pos
192e0 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 itive to enable
192f0 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 triggers or nega
19300 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 tive to leave th
19310 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e e setting unchan
19320 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f ged..** The seco
19330 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 nd parameter is
19340 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
19350 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 integer into whi
19360 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e ch.** is written
19370 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 0 or 1 to indic
19380 61 74 65 20 77 68 65 74 68 65 72 20 74 72 69 67 ate whether trig
19390 67 65 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 gers are disable
193a0 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 d or enabled.**
193b0 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 following this c
193c0 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 all. The second
193d0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 parameter may b
193e0 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 e a NULL pointer
193f0 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 , in.** which ca
19400 73 65 20 74 68 65 20 74 72 69 67 67 65 72 20 73 se the trigger s
19410 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 etting is not re
19420 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 ported back. </d
19430 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a d>.**.** </dl>.*
19440 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
19450 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 _DBCONFIG_LOOKAS
19460 49 44 45 20 20 20 20 20 20 20 31 30 30 31 20 20 IDE 1001
19470 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 /* void* int int
19480 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
19490 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 TE_DBCONFIG_ENAB
194a0 4c 45 5f 46 4b 45 59 20 20 20 20 20 31 30 30 32 LE_FKEY 1002
194b0 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f /* int int* */
194c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
194d0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f DBCONFIG_ENABLE_
194e0 54 52 49 47 47 45 52 20 20 31 30 30 33 20 20 2f TRIGGER 1003 /
194f0 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a * int int* */...
19500 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
19510 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c Enable Or Disabl
19520 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c e Extended Resul
19530 74 20 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f t Codes.** METHO
19540 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a D: sqlite3.**.**
19550 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 ^The sqlite3_ex
19560 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f tended_result_co
19570 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e des() routine en
19580 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 ables or disable
19590 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 s the.** [extend
195a0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d ed result codes]
195b0 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 feature of SQLi
195c0 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 te. ^The extende
195d0 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 d result.** code
195e0 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 s are disabled b
195f0 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 y default for hi
19600 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 storical compati
19610 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54 bility..*/.SQLIT
19620 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
19630 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
19640 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 _extended_result
19650 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c _codes(sqlite3*,
19660 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a int onoff);../*
19670 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 .** CAPI3REF: La
19680 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a st Insert Rowid.
19690 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
196a0 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 e3.**.** ^Each e
196b0 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c ntry in most SQL
196c0 69 74 65 20 74 61 62 6c 65 73 20 28 65 78 63 65 ite tables (exce
196d0 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55 54 20 pt for [WITHOUT
196e0 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a ROWID] tables).*
196f0 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 * has a unique 6
19700 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 4-bit signed.**
19710 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c integer key call
19720 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 ed the [ROWID |
19730 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 "rowid"]. ^The r
19740 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 owid is always a
19750 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 vailable.** as a
19760 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c n undeclared col
19770 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c umn named ROWID,
19780 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f OID, or _ROWID_
19790 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 as long as thos
197a0 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e e.** names are n
197b0 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 ot also used by
197c0 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 explicitly decla
197d0 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 red columns. ^If
197e0 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 .** the table ha
197f0 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 s a column of ty
19800 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d pe [INTEGER PRIM
19810 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 ARY KEY] then th
19820 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 at column.** is
19830 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f another alias fo
19840 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a r the rowid..**.
19850 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
19860 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 last_insert_rowi
19870 64 28 44 29 20 69 6e 74 65 72 66 61 63 65 20 72 d(D) interface r
19880 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 eturns the [rowi
19890 64 5d 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6d 6f d] of the .** mo
198a0 73 74 20 72 65 63 65 6e 74 20 73 75 63 63 65 73 st recent succes
198b0 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e sful [INSERT] in
198c0 74 6f 20 61 20 72 6f 77 69 64 20 74 61 62 6c 65 to a rowid table
198d0 20 6f 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62 or [virtual tab
198e0 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 le].** on databa
198f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e se connection D.
19900 0a 2a 2a 20 5e 49 6e 73 65 72 74 73 20 69 6e 74 .** ^Inserts int
19910 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44 o [WITHOUT ROWID
19920 5d 20 74 61 62 6c 65 73 20 61 72 65 20 6e 6f 74 ] tables are not
19930 20 72 65 63 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49 recorded..** ^I
19940 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 f no successful
19950 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f 20 72 [INSERT]s into r
19960 6f 77 69 64 20 74 61 62 6c 65 73 0a 2a 2a 20 68 owid tables.** h
19970 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 ave ever occurre
19980 64 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 d on the databas
19990 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 e connection D,
199a0 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 .** then sqlite3
199b0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 _last_insert_row
199c0 69 64 28 44 29 20 72 65 74 75 72 6e 73 20 7a 65 id(D) returns ze
199d0 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 ro..**.** ^(If a
199e0 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 n [INSERT] occur
199f0 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 s within a trigg
19a00 65 72 20 6f 72 20 77 69 74 68 69 6e 20 61 20 5b er or within a [
19a10 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a virtual table].*
19a20 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 * method, then t
19a30 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c his routine will
19a40 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 return the [row
19a50 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 id] of the inser
19a60 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f ted.** row as lo
19a70 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65 ng as the trigge
19a80 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 r or virtual tab
19a90 6c 65 20 6d 65 74 68 6f 64 20 69 73 20 72 75 6e le method is run
19aa0 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 ning..** But onc
19ab0 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 e the trigger or
19ac0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d virtual table m
19ad0 65 74 68 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 ethod ends, the
19ae0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a value returned .
19af0 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 ** by this routi
19b00 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 77 68 ne reverts to wh
19b10 61 74 20 69 74 20 77 61 73 20 62 65 66 6f 72 65 at it was before
19b20 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 the trigger or
19b30 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 virtual.** table
19b40 20 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e method began.)^
19b50 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 .**.** ^An [INSE
19b60 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 RT] that fails d
19b70 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 ue to a constrai
19b80 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 nt violation is
19b90 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 not a.** success
19ba0 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 ful [INSERT] and
19bb0 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 does not change
19bc0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 the value retur
19bd0 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 ned by this.** r
19be0 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 outine. ^Thus I
19bf0 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 NSERT OR FAIL, I
19c00 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c NSERT OR IGNORE,
19c10 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 INSERT OR ROLLB
19c20 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 ACK,.** and INSE
19c30 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 RT OR ABORT make
19c40 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 no changes to t
19c50 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
19c60 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 of this.** routi
19c70 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e ne when their in
19c80 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 sertion fails.
19c90 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 ^(When INSERT OR
19ca0 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f REPLACE.** enco
19cb0 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 unters a constra
19cc0 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 int violation, i
19cd0 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e t does not fail.
19ce0 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 The.** INSERT
19cf0 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d continues to com
19d00 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 pletion after de
19d10 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 leting rows that
19d20 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 caused.** the c
19d30 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 onstraint proble
19d40 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 m so INSERT OR R
19d50 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 EPLACE will alwa
19d60 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 ys change.** the
19d70 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 return value of
19d80 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e this interface.
19d90 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 )^.**.** ^For th
19da0 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 e purposes of th
19db0 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b is routine, an [
19dc0 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 INSERT] is consi
19dd0 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 dered to.** be s
19de0 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 uccessful even i
19df0 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65 f it is subseque
19e00 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b ntly rolled back
19e10 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e ..**.** This fun
19e20 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 ction is accessi
19e30 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 ble to SQL state
19e40 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a ments via the.**
19e50 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f [last_insert_ro
19e60 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 wid() SQL functi
19e70 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 on]..**.** If a
19e80 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 separate thread
19e90 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b performs a new [
19ea0 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 INSERT] on the s
19eb0 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 ame.** database
19ec0 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 connection while
19ed0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 the [sqlite3_la
19ee0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 st_insert_rowid(
19ef0 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 )].** function i
19f00 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 s running and th
19f10 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c us changes the l
19f20 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 ast insert [rowi
19f30 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 d],.** then the
19f40 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 value returned b
19f50 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f y [sqlite3_last_
19f60 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 insert_rowid()]
19f70 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 is.** unpredicta
19f80 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f ble and might no
19f90 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 t equal either t
19fa0 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 he old or the ne
19fb0 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 w.** last insert
19fc0 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c [rowid]..*/.SQL
19fd0 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f ITE_API sqlite3_
19fe0 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 54 44 int64 SQLITE_STD
19ff0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6c 61 73 CALL sqlite3_las
1a000 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 t_insert_rowid(s
1a010 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a qlite3*);../*.**
1a020 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 CAPI3REF: Count
1a030 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 The Number Of R
1a040 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 ows Modified.**
1a050 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a METHOD: sqlite3.
1a060 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 **.** ^This func
1a070 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 tion returns the
1a080 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 number of rows
1a090 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 72 74 modified, insert
1a0a0 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 ed or.** deleted
1a0b0 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 by the most rec
1a0c0 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 ently completed
1a0d0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f INSERT, UPDATE o
1a0e0 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 r DELETE.** stat
1a0f0 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 64 61 74 ement on the dat
1a100 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1a110 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 specified by th
1a120 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 e only parameter
1a130 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69 6e 67 20 ..** ^Executing
1a140 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f any other type o
1a150 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 f SQL statement
1a160 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20 does not modify
1a170 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 the value.** ret
1a180 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 urned by this fu
1a190 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f nction..**.** ^O
1a1a0 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65 nly changes made
1a1b0 20 64 69 72 65 63 74 6c 79 20 62 79 20 74 68 65 directly by the
1a1c0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 INSERT, UPDATE
1a1d0 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d or DELETE statem
1a1e0 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 ent are.** consi
1a1f0 64 65 72 65 64 20 2d 20 61 75 78 69 6c 69 61 72 dered - auxiliar
1a200 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 y changes caused
1a210 20 62 79 20 5b 43 52 45 41 54 45 20 54 52 49 47 by [CREATE TRIG
1a220 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2c GER | triggers],
1a230 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 .** [foreign ke
1a240 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 y actions] or [R
1a250 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 EPLACE] constrai
1a260 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 nt resolution ar
1a270 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a e not counted..*
1a280 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f * .** Changes to
1a290 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65 a view that are
1a2a0 20 69 6e 74 65 72 63 65 70 74 65 64 20 62 79 20 intercepted by
1a2b0 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 .** [INSTEAD OF
1a2c0 74 72 69 67 67 65 72 20 7c 20 49 4e 53 54 45 41 trigger | INSTEA
1a2d0 44 20 4f 46 20 74 72 69 67 67 65 72 73 5d 20 61 D OF triggers] a
1a2e0 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 re not counted.
1a2f0 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72 ^The value .** r
1a300 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 eturned by sqlit
1a310 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6d 6d e3_changes() imm
1a320 65 64 69 61 74 65 6c 79 20 61 66 74 65 72 20 61 ediately after a
1a330 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 n INSERT, UPDATE
1a340 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73 or .** DELETE s
1a350 74 61 74 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 tatement run on
1a360 61 20 76 69 65 77 20 69 73 20 61 6c 77 61 79 73 a view is always
1a370 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e zero. Only chan
1a380 67 65 73 20 6d 61 64 65 20 74 6f 20 72 65 61 6c ges made to real
1a390 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61 72 65 20 .** tables are
1a3a0 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 counted..**.** T
1a3b0 68 69 6e 67 73 20 61 72 65 20 6d 6f 72 65 20 63 hings are more c
1a3c0 6f 6d 70 6c 69 63 61 74 65 64 20 69 66 20 74 68 omplicated if th
1a3d0 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 e sqlite3_change
1a3e0 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a s() function is.
1a3f0 2a 2a 20 65 78 65 63 75 74 65 64 20 77 68 69 6c ** executed whil
1a400 65 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 e a trigger prog
1a410 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 ram is running.
1a420 54 68 69 73 20 6d 61 79 20 68 61 70 70 65 6e 20 This may happen
1a430 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61 if the.** progra
1a440 6d 20 75 73 65 73 20 74 68 65 20 5b 63 68 61 6e m uses the [chan
1a450 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 ges() SQL functi
1a460 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20 on], or if some
1a470 6f 74 68 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a other callback.*
1a480 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b * function invok
1a490 65 73 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 es sqlite3_chang
1a4a0 65 73 28 29 20 64 69 72 65 63 74 6c 79 2e 20 45 es() directly. E
1a4b0 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a ssentially:.** .
1a4c0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 ** <ul>.** <li
1a4d0 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e 74 65 72 > ^(Before enter
1a4e0 69 6e 67 20 61 20 74 72 69 67 67 65 72 20 70 72 ing a trigger pr
1a4f0 6f 67 72 61 6d 20 74 68 65 20 76 61 6c 75 65 20 ogram the value
1a500 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 returned by.**
1a510 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 68 sqlite3_ch
1a520 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e anges() function
1a530 20 69 73 20 73 61 76 65 64 2e 20 41 66 74 65 72 is saved. After
1a540 20 74 68 65 20 74 72 69 67 67 65 72 20 70 72 6f the trigger pro
1a550 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20 gram .**
1a560 68 61 73 20 66 69 6e 69 73 68 65 64 2c 20 74 68 has finished, th
1a570 65 20 6f 72 69 67 69 6e 61 6c 20 76 61 6c 75 65 e original value
1a580 20 69 73 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a is restored.)^.
1a590 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 ** .** <li> ^(
1a5a0 57 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 Within a trigger
1a5b0 20 70 72 6f 67 72 61 6d 20 65 61 63 68 20 49 4e program each IN
1a5c0 53 45 52 54 2c 20 55 50 44 41 54 45 20 61 6e 64 SERT, UPDATE and
1a5d0 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20 DELETE .**
1a5e0 20 20 20 73 74 61 74 65 6d 65 6e 74 20 73 65 74 statement set
1a5f0 73 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 s the value retu
1a600 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f rned by sqlite3_
1a610 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 changes() .**
1a620 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 upon comple
1a630 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 tion as normal.
1a640 4f 66 20 63 6f 75 72 73 65 2c 20 74 68 69 73 20 Of course, this
1a650 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69 value will not i
1a660 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20 20 20 20 nclude .**
1a670 20 20 61 6e 79 20 63 68 61 6e 67 65 73 20 70 65 any changes pe
1a680 72 66 6f 72 6d 65 64 20 62 79 20 73 75 62 2d 74 rformed by sub-t
1a690 72 69 67 67 65 72 73 2c 20 61 73 20 74 68 65 20 riggers, as the
1a6a0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 sqlite3_changes(
1a6b0 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 76 61 6c ) .** val
1a6c0 75 65 20 77 69 6c 6c 20 62 65 20 73 61 76 65 64 ue will be saved
1a6d0 20 61 6e 64 20 72 65 73 74 6f 72 65 64 20 61 66 and restored af
1a6e0 74 65 72 20 65 61 63 68 20 73 75 62 2d 74 72 69 ter each sub-tri
1a6f0 67 67 65 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a gger has run.)^.
1a700 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 ** </ul>.** .**
1a710 5e 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 ^This means that
1a720 20 69 66 20 74 68 65 20 63 68 61 6e 67 65 73 28 if the changes(
1a730 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28 ) SQL function (
1a740 6f 72 20 73 69 6d 69 6c 61 72 29 20 69 73 20 75 or similar) is u
1a750 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 sed.** by the fi
1a760 72 73 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 rst INSERT, UPDA
1a770 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 TE or DELETE sta
1a780 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 tement within a
1a790 74 72 69 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20 trigger, it .**
1a7a0 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 returns the valu
1a7b0 65 20 61 73 20 73 65 74 20 77 68 65 6e 20 74 68 e as set when th
1a7c0 65 20 63 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d e calling statem
1a7d0 65 6e 74 20 62 65 67 61 6e 20 65 78 65 63 75 74 ent began execut
1a7e0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 ing..** ^If it i
1a7f0 73 20 75 73 65 64 20 62 79 20 74 68 65 20 73 65 s used by the se
1a800 63 6f 6e 64 20 6f 72 20 73 75 62 73 65 71 75 65 cond or subseque
1a810 6e 74 20 73 75 63 68 20 73 74 61 74 65 6d 65 6e nt such statemen
1a820 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 t within a trigg
1a830 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 er .** program,
1a840 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
1a850 65 64 20 72 65 66 6c 65 63 74 73 20 74 68 65 20 ed reflects the
1a860 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d number of rows m
1a870 6f 64 69 66 69 65 64 20 62 79 20 74 68 65 20 0a odified by the .
1a880 2a 2a 20 70 72 65 76 69 6f 75 73 20 49 4e 53 45 ** previous INSE
1a890 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 RT, UPDATE or DE
1a8a0 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 LETE statement w
1a8b0 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 74 ithin the same t
1a8c0 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 rigger..**.** Se
1a8d0 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 e also the [sqli
1a8e0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 te3_total_change
1a8f0 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 s()] interface,
1a900 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 the.** [count_ch
1a910 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 anges pragma], a
1a920 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 nd the [changes(
1a930 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e ) SQL function].
1a940 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 .**.** If a sepa
1a950 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 rate thread make
1a960 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 s changes on the
1a970 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 same database c
1a980 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 onnection.** whi
1a990 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e le [sqlite3_chan
1a9a0 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e ges()] is runnin
1a9b0 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 g then the value
1a9c0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 returned.** is
1a9d0 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e unpredictable an
1a9e0 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c d not meaningful
1a9f0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
1aa00 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 int SQLITE_STDCA
1aa10 4c 4c 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 LL sqlite3_chang
1aa20 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f es(sqlite3*);../
1aa30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 *.** CAPI3REF: T
1aa40 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 otal Number Of R
1aa50 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 ows Modified.**
1aa60 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a METHOD: sqlite3.
1aa70 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 **.** ^This func
1aa80 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 tion returns the
1aa90 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 total number of
1aaa0 20 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20 rows inserted,
1aab0 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 modified or.** d
1aac0 65 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 eleted by all [I
1aad0 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d NSERT], [UPDATE]
1aae0 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 or [DELETE] sta
1aaf0 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 tements complete
1ab00 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64 d.** since the d
1ab10 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1ab20 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 on was opened, i
1ab30 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65 ncluding those e
1ab40 78 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 xecuted as.** pa
1ab50 72 74 20 6f 66 20 74 72 69 67 67 65 72 20 70 72 rt of trigger pr
1ab60 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 ograms. ^Executi
1ab70 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 ng any other typ
1ab80 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 e of SQL stateme
1ab90 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 nt.** does not a
1aba0 66 66 65 63 74 20 74 68 65 20 76 61 6c 75 65 20 ffect the value
1abb0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 returned by sqli
1abc0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 te3_total_change
1abd0 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 s()..** .** ^Cha
1abe0 6e 67 65 73 20 6d 61 64 65 20 61 73 20 70 61 72 nges made as par
1abf0 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 t of [foreign ke
1ac00 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 y actions] are i
1ac10 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a ncluded in the.*
1ac20 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f * count, but tho
1ac30 73 65 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 se made as part
1ac40 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 of REPLACE const
1ac50 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e raint resolution
1ac60 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 are.** not. ^Ch
1ac70 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 anges to a view
1ac80 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 that are interce
1ac90 70 74 65 64 20 62 79 20 49 4e 53 54 45 41 44 20 pted by INSTEAD
1aca0 4f 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 OF triggers .**
1acb0 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e are not counted.
1acc0 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f .** .** See also
1acd0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 the [sqlite3_ch
1ace0 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 anges()] interfa
1acf0 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e ce, the.** [coun
1ad00 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 t_changes pragma
1ad10 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 ], and the [tota
1ad20 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 l_changes() SQL
1ad30 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a function]..**.**
1ad40 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 If a separate t
1ad50 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e hread makes chan
1ad60 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 ges on the same
1ad70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1ad80 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 ion.** while [sq
1ad90 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e lite3_total_chan
1ada0 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e ges()] is runnin
1adb0 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 g then the value
1adc0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 .** returned is
1add0 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e unpredictable an
1ade0 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c d not meaningful
1adf0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
1ae00 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 int SQLITE_STDCA
1ae10 4c 4c 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c LL sqlite3_total
1ae20 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 _changes(sqlite3
1ae30 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
1ae40 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 REF: Interrupt A
1ae50 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 Long-Running Qu
1ae60 65 72 79 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 ery.** METHOD: s
1ae70 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 qlite3.**.** ^Th
1ae80 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 is function caus
1ae90 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 es any pending d
1aea0 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f atabase operatio
1aeb0 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a n to abort and.*
1aec0 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 * return at its
1aed0 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 earliest opportu
1aee0 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 nity. This routi
1aef0 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a ne is typically.
1af00 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 ** called in res
1af10 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 ponse to a user
1af20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 action such as p
1af30 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 ressing "Cancel"
1af40 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 .** or Ctrl-C wh
1af50 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e ere the user wan
1af60 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 ts a long query
1af70 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c operation to hal
1af80 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 t.** immediately
1af90 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 ..**.** ^It is s
1afa0 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 afe to call this
1afb0 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 routine from a
1afc0 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 thread different
1afd0 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 from the.** thr
1afe0 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72 ead that is curr
1aff0 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 ently running th
1b000 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 e database opera
1b010 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a tion. But it.**
1b020 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 is not safe to
1b030 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e call this routin
1b040 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 e with a [databa
1b050 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 se connection] t
1b060 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 hat.** is closed
1b070 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 or might close
1b080 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 before sqlite3_i
1b090 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72 nterrupt() retur
1b0a0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e ns..**.** ^If an
1b0b0 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 SQL operation i
1b0c0 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 s very nearly fi
1b0d0 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69 nished at the ti
1b0e0 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 me when.** sqlit
1b0f0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 e3_interrupt() i
1b100 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 s called, then i
1b110 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 t might not have
1b120 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a an opportunity.
1b130 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 ** to be interru
1b140 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 pted and might c
1b150 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c ontinue to compl
1b160 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e etion..**.** ^An
1b170 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 SQL operation t
1b180 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 hat is interrupt
1b190 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b ed will return [
1b1a0 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 SQLITE_INTERRUPT
1b1b0 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e ]..** ^If the in
1b1c0 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 terrupted SQL op
1b1d0 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e eration is an IN
1b1e0 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 SERT, UPDATE, or
1b1f0 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 DELETE.** that
1b200 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 is inside an exp
1b210 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f licit transactio
1b220 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 n, then the enti
1b230 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a re transaction.*
1b240 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 * will be rolled
1b250 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 back automatica
1b260 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 lly..**.** ^The
1b270 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
1b280 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 t(D) call is in
1b290 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c effect until all
1b2a0 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 currently runni
1b2b0 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d ng.** SQL statem
1b2c0 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 ents on [databas
1b2d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 e connection] D
1b2e0 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 complete. ^Any
1b2f0 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e new SQL statemen
1b300 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 ts.** that are s
1b310 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 tarted after the
1b320 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
1b330 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 pt() call and be
1b340 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e fore the .** run
1b350 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 ning statements
1b360 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 reaches zero are
1b370 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 interrupted as
1b380 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e if they had been
1b390 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f .** running prio
1b3a0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 r to the sqlite3
1b3b0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c _interrupt() cal
1b3c0 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 l. ^New SQL sta
1b3d0 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 tements.** that
1b3e0 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 are started afte
1b3f0 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 r the running st
1b400 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 atement count re
1b410 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a aches zero are.*
1b420 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 * not effected b
1b430 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e y the sqlite3_in
1b440 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 terrupt()..** ^A
1b450 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
1b460 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 _interrupt(D) th
1b470 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 at occurs when t
1b480 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e here are no runn
1b490 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 ing.** SQL state
1b4a0 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 ments is a no-op
1b4b0 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 and has no effe
1b4c0 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d ct on SQL statem
1b4d0 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 ents.** that are
1b4e0 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 started after t
1b4f0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 he sqlite3_inter
1b500 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 rupt() call retu
1b510 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 rns..**.** If th
1b520 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
1b530 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 ction closes whi
1b540 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 le [sqlite3_inte
1b550 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 rrupt()].** is r
1b560 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 unning then bad
1b570 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 things will like
1b580 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51 ly happen..*/.SQ
1b590 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 LITE_API void SQ
1b5a0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
1b5b0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 ite3_interrupt(s
1b5c0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a qlite3*);../*.**
1b5d0 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 CAPI3REF: Deter
1b5e0 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 mine If An SQL S
1b5f0 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 tatement Is Comp
1b600 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 lete.**.** These
1b610 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 routines are us
1b620 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d eful during comm
1b630 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 and-line input t
1b640 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 o determine if t
1b650 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 he.** currently
1b660 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65 entered text see
1b670 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d ms to form a com
1b680 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d plete SQL statem
1b690 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 ent or.** if add
1b6a0 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 itional input is
1b6b0 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 needed before s
1b6c0 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 ending the text
1b6d0 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 into.** SQLite f
1b6e0 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 or parsing. ^Th
1b6f0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 ese routines ret
1b700 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 urn 1 if the inp
1b710 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 ut string.** app
1b720 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d ears to be a com
1b730 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d plete SQL statem
1b740 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 ent. ^A stateme
1b750 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 nt is judged to
1b760 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 be.** complete i
1b770 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 f it ends with a
1b780 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e semicolon token
1b790 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 and is not a pr
1b7a0 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c efix of a.** wel
1b7b0 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 l-formed CREATE
1b7c0 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e TRIGGER statemen
1b7d0 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 t. ^Semicolons
1b7e0 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 that are embedde
1b7f0 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 d within.** stri
1b800 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 ng literals or q
1b810 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 uoted identifier
1b820 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e names or commen
1b830 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e ts are not.** in
1b840 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 dependent tokens
1b850 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20 (they are part
1b860 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 of the token in
1b870 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a which they are.*
1b880 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 * embedded) and
1b890 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e thus do not coun
1b8a0 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 t as a statement
1b8b0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 terminator. ^W
1b8c0 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 hitespace.** and
1b8d0 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 comments that f
1b8e0 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 ollow the final
1b8f0 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 semicolon are ig
1b900 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 nored..**.** ^Th
1b910 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 ese routines ret
1b920 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 urn 0 if the sta
1b930 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 tement is incomp
1b940 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 lete. ^If a.**
1b950 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
1b960 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 n fails, then SQ
1b970 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 LITE_NOMEM is re
1b980 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 turned..**.** ^T
1b990 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f hese routines do
1b9a0 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 not parse the S
1b9b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 QL statements th
1b9c0 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 us.** will not d
1b9d0 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 etect syntactica
1b9e0 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 lly incorrect SQ
1b9f0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 L..**.** ^(If SQ
1ba00 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 Lite has not bee
1ba10 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 n initialized us
1ba20 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 ing [sqlite3_ini
1ba30 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 tialize()] prior
1ba40 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 .** to invoking
1ba50 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 sqlite3_complet
1ba60 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 e16() then sqlit
1ba70 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
1ba80 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 is invoked.** au
1ba90 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 tomatically by s
1baa0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 qlite3_complete1
1bab0 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 6(). If that in
1bac0 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 itialization fai
1bad0 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 ls,.** then the
1bae0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f return value fro
1baf0 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 m sqlite3_comple
1bb00 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e te16() will be n
1bb10 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 on-zero.** regar
1bb20 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 dless of whether
1bb30 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 or not the inpu
1bb40 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 t SQL is complet
1bb50 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 e.)^.**.** The i
1bb60 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 nput to [sqlite3
1bb70 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 _complete()] mus
1bb80 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d t be a zero-term
1bb90 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 inated.** UTF-8
1bba0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 string..**.** Th
1bbb0 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 e input to [sqli
1bbc0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 te3_complete16()
1bbd0 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f ] must be a zero
1bbe0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 -terminated.** U
1bbf0 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 TF-16 string in
1bc00 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 native byte orde
1bc10 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 r..*/.SQLITE_API
1bc20 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
1bc30 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 ALL sqlite3_comp
1bc40 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 lete(const char
1bc50 2a 73 71 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 *sql);.SQLITE_AP
1bc60 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
1bc70 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6d CALL sqlite3_com
1bc80 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f plete16(const vo
1bc90 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a id *sql);../*.**
1bca0 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 CAPI3REF: Regis
1bcb0 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 ter A Callback T
1bcc0 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f o Handle SQLITE_
1bcd0 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20 4b BUSY Errors.** K
1bce0 45 59 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d 68 EYWORDS: {busy-h
1bcf0 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 7d andler callback}
1bd00 20 7b 62 75 73 79 20 68 61 6e 64 6c 65 72 7d 0a {busy handler}.
1bd10 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
1bd20 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 e3.**.** ^The sq
1bd30 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c lite3_busy_handl
1bd40 65 72 28 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e er(D,X,P) routin
1bd50 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 e sets a callbac
1bd60 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 k function X.**
1bd70 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e that might be in
1bd80 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d voked with argum
1bd90 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a ent P whenever.*
1bda0 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 * an attempt is
1bdb0 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 61 made to access a
1bdc0 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 database table
1bdd0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a associated with.
1bde0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
1bdf0 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20 nection] D when
1be00 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a another thread.*
1be10 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 * or process has
1be20 20 74 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65 the table locke
1be30 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 d..** The sqlite
1be40 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 3_busy_handler()
1be50 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 interface is us
1be60 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a ed to implement.
1be70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 ** [sqlite3_busy
1be80 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20 _timeout()] and
1be90 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d [PRAGMA busy_tim
1bea0 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 eout]..**.** ^If
1beb0 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 the busy callba
1bec0 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e ck is NULL, then
1bed0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a [SQLITE_BUSY].*
1bee0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d * is returned im
1bef0 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 mediately upon e
1bf00 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 ncountering the
1bf10 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 lock. ^If the b
1bf20 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 usy callback.**
1bf30 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 is not NULL, the
1bf40 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d n the callback m
1bf50 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 ight be invoked
1bf60 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e with two argumen
1bf70 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 ts..**.** ^The f
1bf80 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
1bf90 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 the busy handle
1bfa0 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 r is a copy of t
1bfb0 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 he void* pointer
1bfc0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 which.** is the
1bfd0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 third argument
1bfe0 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f to sqlite3_busy_
1bff0 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 handler(). ^The
1c000 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
1c010 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 to.** the busy
1c020 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b handler callback
1c030 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f is the number o
1c040 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 f times that the
1c050 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 busy handler ha
1c060 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 s.** been invoke
1c070 64 20 70 72 65 76 69 6f 75 73 6c 79 20 66 6f 72 d previously for
1c080 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e the same lockin
1c090 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 g event. ^If th
1c0a0 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 e.** busy callba
1c0b0 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 ck returns 0, th
1c0c0 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c en no additional
1c0d0 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 attempts are ma
1c0e0 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 de to.** access
1c0f0 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 the database and
1c100 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 [SQLITE_BUSY] i
1c110 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f s returned.** to
1c120 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
1c130 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c ..** ^If the cal
1c140 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f lback returns no
1c150 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f n-zero, then ano
1c160 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 ther attempt.**
1c170 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 is made to acces
1c180 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 s the database a
1c190 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 nd the cycle rep
1c1a0 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 eats..**.** The
1c1b0 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 presence of a bu
1c1c0 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 sy handler does
1c1d0 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 not guarantee th
1c1e0 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e at it will be in
1c1f0 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 voked.** when th
1c200 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 ere is lock cont
1c210 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 ention. ^If SQLi
1c220 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 te determines th
1c230 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 at invoking the
1c240 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 busy.** handler
1c250 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 could result in
1c260 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 a deadlock, it w
1c270 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 ill go ahead and
1c280 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
1c290 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 BUSY].** to the
1c2a0 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74 application inst
1c2b0 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 ead of invoking
1c2c0 74 68 65 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e the .** busy han
1c2d0 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 dler..** Conside
1c2e0 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 r a scenario whe
1c2f0 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 re one process i
1c300 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 s holding a read
1c310 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 lock that.** it
1c320 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 is trying to pr
1c330 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 omote to a reser
1c340 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 ved lock and.**
1c350 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 a second process
1c360 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 is holding a re
1c370 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 served lock that
1c380 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a it is trying.**
1c390 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 to promote to a
1c3a0 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b n exclusive lock
1c3b0 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f . The first pro
1c3c0 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 cess cannot proc
1c3d0 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 eed.** because i
1c3e0 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 t is blocked by
1c3f0 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 the second and t
1c400 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 he second proces
1c410 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 s cannot.** proc
1c420 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69 eed because it i
1c430 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 s blocked by the
1c440 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 first. If both
1c450 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e processes.** in
1c460 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 voke the busy ha
1c470 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 ndlers, neither
1c480 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 will make any pr
1c490 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f ogress. Therefo
1c4a0 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 re,.** SQLite re
1c4b0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 turns [SQLITE_BU
1c4c0 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 SY] for the firs
1c4d0 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e t process, hopin
1c4e0 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 g that this.** w
1c4f0 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 ill induce the f
1c500 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 irst process to
1c510 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 release its read
1c520 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a lock and allow.
1c530 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 ** the second pr
1c540 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 ocess to proceed
1c550 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 ..**.** ^The def
1c560 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 ault busy callba
1c570 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a ck is NULL..**.*
1c580 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e * ^(There can on
1c590 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 ly be a single b
1c5a0 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 usy handler defi
1c5b0 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 ned for each.**
1c5c0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
1c5d0 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 tion]. Setting
1c5e0 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c a new busy handl
1c5f0 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a er clears any.**
1c600 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 previously set
1c610 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 handler.)^ ^Not
1c620 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b e that calling [
1c630 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d sqlite3_busy_tim
1c640 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 eout()].** or ev
1c650 61 6c 75 61 74 69 6e 67 20 5b 50 52 41 47 4d 41 aluating [PRAGMA
1c660 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d busy_timeout=N]
1c670 20 77 69 6c 6c 20 63 68 61 6e 67 65 20 74 68 65 will change the
1c680 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 .** busy handler
1c690 20 61 6e 64 20 74 68 75 73 20 63 6c 65 61 72 20 and thus clear
1c6a0 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 73 any previously s
1c6b0 65 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e et busy handler.
1c6c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 .**.** The busy
1c6d0 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 callback should
1c6e0 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 not take any act
1c6f0 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 ions which modif
1c700 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 y the.** databas
1c710 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 e connection tha
1c720 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 t invoked the bu
1c730 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20 sy handler. In
1c740 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 other words,.**
1c750 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 the busy handler
1c760 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e is not reentran
1c770 74 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 t. Any such act
1c780 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 ions.** result i
1c790 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 n undefined beha
1c7a0 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 vior..** .** A b
1c7b0 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 usy handler must
1c7c0 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 not close the d
1c7d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1c7e0 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 on.** or [prepar
1c7f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 ed statement] th
1c800 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 at invoked the b
1c810 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a usy handler..*/.
1c820 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
1c830 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
1c840 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c lite3_busy_handl
1c850 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 er(sqlite3*, int
1c860 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 (*)(void*,int),
1c870 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 void*);../*.** C
1c880 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 API3REF: Set A B
1c890 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d usy Timeout.** M
1c8a0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a ETHOD: sqlite3.*
1c8b0 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 *.** ^This routi
1c8c0 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 ne sets a [sqlit
1c8d0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 e3_busy_handler
1c8e0 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 | busy handler]
1c8f0 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 that sleeps.** f
1c900 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61 or a specified a
1c910 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 mount of time wh
1c920 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f en a table is lo
1c930 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 cked. ^The hand
1c940 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 ler.** will slee
1c950 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 p multiple times
1c960 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 until at least
1c970 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 "ms" millisecond
1c980 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a s of sleeping.**
1c990 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 have accumulate
1c9a0 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 d. ^After at le
1c9b0 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 ast "ms" millise
1c9c0 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e conds of sleepin
1c9d0 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 g,.** the handle
1c9e0 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 r returns 0 whic
1c9f0 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 h causes [sqlite
1ca00 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 3_step()] to ret
1ca10 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 urn.** [SQLITE_B
1ca20 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c USY]..**.** ^Cal
1ca30 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e ling this routin
1ca40 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 e with an argume
1ca50 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 nt less than or
1ca60 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a equal to zero.**
1ca70 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 turns off all b
1ca80 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a usy handlers..**
1ca90 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 .** ^(There can
1caa0 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 only be a single
1cab0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f busy handler fo
1cac0 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a r a particular.*
1cad0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e * [database conn
1cae0 65 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67 ection] at any g
1caf0 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 iven moment. If
1cb00 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 another busy ha
1cb10 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 ndler.** was def
1cb20 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 ined (using [sq
1cb30 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c lite3_busy_handl
1cb40 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 er()]) prior to
1cb50 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 calling.** this
1cb60 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 routine, that ot
1cb70 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 her busy handler
1cb80 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a is cleared.)^.*
1cb90 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 *.** See also:
1cba0 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d [PRAGMA busy_tim
1cbb0 65 6f 75 74 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f eout].*/.SQLITE_
1cbc0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 API int SQLITE_S
1cbd0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 TDCALL sqlite3_b
1cbe0 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 usy_timeout(sqli
1cbf0 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a te3*, int ms);..
1cc00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1cc10 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 Convenience Rout
1cc20 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 ines For Running
1cc30 20 51 75 65 72 69 65 73 0a 2a 2a 20 4d 45 54 48 Queries.** METH
1cc40 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a OD: sqlite3.**.*
1cc50 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61 * This is a lega
1cc60 63 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 cy interface tha
1cc70 74 20 69 73 20 70 72 65 73 65 72 76 65 64 20 66 t is preserved f
1cc80 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d or backwards com
1cc90 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 patibility..** U
1cca0 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 se of this inter
1ccb0 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f face is not reco
1ccc0 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 mmended..**.** D
1ccd0 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e efinition: A <b>
1cce0 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e result table</b>
1ccf0 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 is memory data
1cd00 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65 structure create
1cd10 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c d by the.** [sql
1cd20 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
1cd30 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 ] interface. A
1cd40 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 result table rec
1cd50 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 ords the.** comp
1cd60 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c lete query resul
1cd70 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d ts from one or m
1cd80 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a ore queries..**.
1cd90 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e ** The table con
1cda0 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 ceptually has a
1cdb0 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 number of rows a
1cdc0 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 nd columns. But
1cdd0 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 .** these number
1cde0 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f s are not part o
1cdf0 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 f the result tab
1ce00 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 le itself. Thes
1ce10 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 e.** numbers are
1ce20 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 obtained separa
1ce30 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 tely. Let N be
1ce40 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f the number of ro
1ce50 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 ws.** and M be t
1ce60 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c he number of col
1ce70 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 umns..**.** A re
1ce80 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e sult table is an
1ce90 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 array of pointe
1cea0 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 rs to zero-termi
1ceb0 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 nated UTF-8 stri
1cec0 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 ngs..** There ar
1ced0 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e e (N+1)*M elemen
1cee0 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e ts in the array.
1cef0 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f The first M po
1cf00 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 inters point.**
1cf10 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 to zero-terminat
1cf20 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 ed strings that
1cf30 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d contain the nam
1cf40 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e es of the column
1cf50 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e s..** The remain
1cf60 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 ing entries all
1cf70 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 point to query r
1cf80 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 esults. NULL va
1cf90 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 lues result.** i
1cfa0 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e n NULL pointers.
1cfb0 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 All other valu
1cfc0 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 es are in their
1cfd0 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 UTF-8 zero-termi
1cfe0 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 nated.** string
1cff0 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 representation a
1d000 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 s returned by [s
1d010 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
1d020 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 xt()]..**.** A r
1d030 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 esult table migh
1d040 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 t consist of one
1d050 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 or more memory
1d060 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 allocations..**
1d070 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 It is not safe t
1d080 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 o pass a result
1d090 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 table directly t
1d0a0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 o [sqlite3_free(
1d0b0 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 )]..** A result
1d0c0 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 table should be
1d0d0 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e deallocated usin
1d0e0 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f g [sqlite3_free_
1d0f0 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 table()]..**.**
1d100 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 ^(As an example
1d110 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 of the result ta
1d120 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 ble format, supp
1d130 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75 ose a query resu
1d140 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c lt.** is as foll
1d150 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 ows:.**.** <bloc
1d160 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 kquote><pre>.**
1d170 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 Name
1d180 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 | Age.**
1d190 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d -------------
1d1a0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 ----------.**
1d1b0 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 Alice
1d1c0 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 | 43.**
1d1d0 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 Bob | 28
1d1e0 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 .** Cindy
1d1f0 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c | 21.** <
1d200 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
1d210 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 e>.**.** There a
1d220 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d re two column (M
1d230 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 ==2) and three r
1d240 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 ows (N==3). Thu
1d250 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 s the.** result
1d260 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 table has 8 entr
1d270 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 ies. Suppose th
1d280 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 e result table i
1d290 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 s stored.** in a
1d2a0 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a n array names az
1d2b0 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a Result. Then az
1d2c0 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 Result holds thi
1d2d0 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a s content:.**.**
1d2e0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 <blockquote><pr
1d2f0 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 e>.** azR
1d300 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 esult[0] = "
1d310 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 Name";.**
1d320 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d azResult[1]
1d330 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 = "Age";.**
1d340 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 azResult[
1d350 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a ;2] = "Alice";.*
1d360 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
1d370 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b t[3] = "43";
1d380 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 .** azRes
1d390 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f ult[4] = "Bo
1d3a0 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a b";.** az
1d3b0 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 Result[5] =
1d3c0 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 "28";.**
1d3d0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 azResult[6]
1d3e0 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 = "Cindy";.**
1d3f0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
1d400 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 1;7] = "21";.**
1d410 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
1d420 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 te>)^.**.** ^The
1d430 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 sqlite3_get_tab
1d440 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 le() function ev
1d450 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d aluates one or m
1d460 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e ore.** semicolon
1d470 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 -separated SQL s
1d480 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 tatements in the
1d490 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
1d4a0 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 UTF-8.** string
1d4b0 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 of its 2nd para
1d4c0 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e meter and return
1d4d0 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 s a result table
1d4e0 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 to the.** point
1d4f0 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 er given in its
1d500 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 3rd parameter..*
1d510 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 *.** After the a
1d520 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 pplication has f
1d530 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65 inished with the
1d540 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c result from sql
1d550 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
1d560 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73 ,.** it must pas
1d570 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 s the result tab
1d580 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 le pointer to sq
1d590 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 lite3_free_table
1d5a0 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a () in order to.*
1d5b0 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 * release the me
1d5c0 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 mory that was ma
1d5d0 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 lloced. Because
1d5e0 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a of the way the.
1d5f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c ** [sqlite3_mall
1d600 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 oc()] happens wi
1d610 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 thin sqlite3_get
1d620 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 _table(), the ca
1d630 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f lling.** functio
1d640 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 n must not try t
1d650 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f o call [sqlite3_
1d660 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 free()] directly
1d670 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 . Only.** [sqli
1d680 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 te3_free_table()
1d690 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c ] is able to rel
1d6a0 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 ease the memory
1d6b0 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 properly and saf
1d6c0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ely..**.** The s
1d6d0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 qlite3_get_table
1d6e0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 () interface is
1d6f0 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 implemented as a
1d700 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a wrapper around.
1d710 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 ** [sqlite3_exec
1d720 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 ()]. The sqlite
1d730 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 3_get_table() ro
1d740 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 utine does not h
1d750 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f ave access.** to
1d760 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 any internal da
1d770 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 ta structures of
1d780 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 SQLite. It use
1d790 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 s only the publi
1d7a0 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 c.** interface d
1d7b0 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 efined here. As
1d7c0 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 a consequence,
1d7d0 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 errors that occu
1d7e0 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 r in the.** wrap
1d7f0 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 per layer outsid
1d800 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 e of the interna
1d810 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 l [sqlite3_exec(
1d820 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a )] call are not.
1d830 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 ** reflected in
1d840 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 subsequent calls
1d850 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 to [sqlite3_err
1d860 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 code()] or.** [s
1d870 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d qlite3_errmsg()]
1d880 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
1d890 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 int SQLITE_STDCA
1d8a0 4c 4c 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 LL sqlite3_get_t
1d8b0 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 able(. sqlite3
1d8c0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a *db, /*
1d8d0 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 An open databas
1d8e0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
1d8f0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 r *zSql, /*
1d900 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 SQL to be evalua
1d910 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a ted */. char **
1d920 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f *pazResult, /
1d930 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 * Results of the
1d940 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 query */. int
1d950 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 *pnRow,
1d960 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 /* Number of r
1d970 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 esult rows writt
1d980 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 en here */. int
1d990 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 *pnColumn,
1d9a0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 /* Number of
1d9b0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 result columns w
1d9c0 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 ritten here */.
1d9d0 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 char **pzErrmsg
1d9e0 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 /* Error
1d9f0 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 msg written here
1da00 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 */.);.SQLITE_AP
1da10 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 I void SQLITE_ST
1da20 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 66 72 DCALL sqlite3_fr
1da30 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a ee_table(char **
1da40 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 result);../*.**
1da50 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 CAPI3REF: Format
1da60 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 ted String Print
1da70 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a ing Functions.**
1da80 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
1da90 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b es are work-alik
1daa0 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 es of the "print
1dab0 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 f()" family of f
1dac0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d unctions.** from
1dad0 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 the standard C
1dae0 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 73 library..** Thes
1daf0 65 20 72 6f 75 74 69 6e 65 73 20 75 6e 64 65 72 e routines under
1db00 73 74 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74 68 stand most of th
1db10 65 20 63 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 e common K&R for
1db20 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 2c matting options,
1db30 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d 65 20 61 64 .** plus some ad
1db40 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 ditional non-sta
1db50 6e 64 61 72 64 20 66 6f 72 6d 61 74 73 2c 20 64 ndard formats, d
1db60 65 74 61 69 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a etailed below..*
1db70 2a 20 4e 6f 74 65 20 74 68 61 74 20 73 6f 6d 65 * Note that some
1db80 20 6f 66 20 74 68 65 20 6d 6f 72 65 20 6f 62 73 of the more obs
1db90 63 75 72 65 20 66 6f 72 6d 61 74 74 69 6e 67 20 cure formatting
1dba0 6f 70 74 69 6f 6e 73 20 66 72 6f 6d 20 72 65 63 options from rec
1dbb0 65 6e 74 0a 2a 2a 20 43 2d 6c 69 62 72 61 72 79 ent.** C-library
1dbc0 20 73 74 61 6e 64 61 72 64 73 20 61 72 65 20 6f standards are o
1dbd0 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 69 73 mitted from this
1dbe0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e implementation.
1dbf0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
1dc00 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e te3_mprintf() an
1dc10 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e d sqlite3_vmprin
1dc20 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 tf() routines wr
1dc30 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 ite their.** res
1dc40 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 ults into memory
1dc50 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b obtained from [
1dc60 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
1dc70 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 ]..** The string
1dc80 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 s returned by th
1dc90 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 ese two routines
1dca0 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 should be.** re
1dcb0 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 leased by [sqlit
1dcc0 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f e3_free()]. ^Bo
1dcd0 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 th routines retu
1dce0 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 rn a.** NULL poi
1dcf0 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 nter if [sqlite3
1dd00 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e _malloc()] is un
1dd10 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 able to allocate
1dd20 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 enough.** memor
1dd30 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 y to hold the re
1dd40 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a sulting string..
1dd50 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 **.** ^(The sqli
1dd60 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 te3_snprintf() r
1dd70 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 outine is simila
1dd80 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 r to "snprintf()
1dd90 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 " from.** the st
1dda0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 andard C library
1ddb0 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 . The result is
1ddc0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 written into th
1ddd0 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 e.** buffer supp
1dde0 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f lied as the seco
1ddf0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f nd parameter who
1de00 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e se size is given
1de10 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 by.** the first
1de20 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 parameter. Note
1de30 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 that the order
1de40 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 of the.** first
1de50 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 two parameters i
1de60 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 s reversed from
1de70 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 snprintf().)^ T
1de80 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 his is an.** his
1de90 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 torical accident
1dea0 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 that cannot be
1deb0 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 fixed without br
1dec0 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 eaking.** backwa
1ded0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 rds compatibilit
1dee0 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 y. ^(Note also
1def0 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 that sqlite3_snp
1df00 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 rintf().** retur
1df10 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
1df20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 its buffer inste
1df30 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 ad of the number
1df40 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 of.** character
1df50 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 s actually writt
1df60 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 en into the buff
1df70 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 er.)^ We admit
1df80 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 that.** the numb
1df90 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 er of characters
1dfa0 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 written would b
1dfb0 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 e a more useful
1dfc0 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 return.** value
1dfd0 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 but we cannot ch
1dfe0 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 ange the impleme
1dff0 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 ntation of sqlit
1e000 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a e3_snprintf().**
1e010 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 now without bre
1e020 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c aking compatibil
1e030 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c ity..**.** ^As l
1e040 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65 ong as the buffe
1e050 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 r size is greate
1e060 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c r than zero, sql
1e070 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a ite3_snprintf().
1e080 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 ** guarantees th
1e090 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73 at the buffer is
1e0a0 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 always zero-ter
1e0b0 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 minated. ^The f
1e0c0 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 irst.** paramete
1e0d0 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 r "n" is the tot
1e0e0 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 al size of the b
1e0f0 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 uffer, including
1e100 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 space for.** th
1e110 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f e zero terminato
1e120 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 r. So the longe
1e130 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 st string that c
1e140 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 an be completely
1e150 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c .** written will
1e160 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 be n-1 characte
1e170 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 rs..**.** ^The s
1e180 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 qlite3_vsnprintf
1e190 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 () routine is a
1e1a0 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 varargs version
1e1b0 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 of sqlite3_snpri
1e1c0 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ntf()..**.** The
1e1d0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 se routines all
1e1e0 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 implement some a
1e1f0 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 dditional format
1e200 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 ting.** options
1e210 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 that are useful
1e220 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 for constructing
1e230 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e SQL statements.
1e240 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 .** All of the u
1e250 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f sual printf() fo
1e260 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 rmatting options
1e270 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 apply. In addi
1e280 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 tion, there.** i
1e290 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 s are "%q", "%Q"
1e2a0 2c 20 22 25 77 22 20 61 6e 64 20 22 25 7a 22 20 , "%w" and "%z"
1e2b0 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e options..**.** ^
1e2c0 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 (The %q option w
1e2d0 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 orks like %s in
1e2e0 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75 that it substitu
1e2f0 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e tes a nul-termin
1e300 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 ated.** string f
1e310 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 rom the argument
1e320 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 list. But %q a
1e330 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 lso doubles ever
1e340 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 y '\'' character
1e350 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 ..** %q is desig
1e360 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 ned for use insi
1e370 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 de a string lite
1e380 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c ral.)^ By doubl
1e390 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a ing each '\''.**
1e3a0 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73 character it es
1e3b0 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61 capes that chara
1e3c0 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 cter and allows
1e3d0 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 it to be inserte
1e3e0 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 d into.** the st
1e3f0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 ring..**.** For
1e400 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 example, assume
1e410 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 the string varia
1e420 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 ble zText contai
1e430 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f ns text as follo
1e440 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b ws:.**.** <block
1e450 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 quote><pre>.**
1e460 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 char *zText = "I
1e470 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 t's a happy day!
1e480 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c ";.** </pre></bl
1e490 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 ockquote>.**.**
1e4a0 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 One can use this
1e4b0 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 text in an SQL
1e4c0 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c statement as fol
1e4d0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f lows:.**.** <blo
1e4e0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a ckquote><pre>.**
1e4f0 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 char *zSQL = s
1e500 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 qlite3_mprintf("
1e510 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c INSERT INTO tabl
1e520 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c e VALUES('%q')",
1e530 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c zText);.** sql
1e540 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 ite3_exec(db, zS
1e550 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a QL, 0, 0, 0);.**
1e560 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a sqlite3_free(z
1e570 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c SQL);.** </pre><
1e580 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
1e590 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25 ** Because the %
1e5a0 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 q format string
1e5b0 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 is used, the '\'
1e5c0 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a ' character in z
1e5d0 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 Text.** is escap
1e5e0 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 ed and the SQL g
1e5f0 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66 enerated is as f
1e600 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 ollows:.**.** <b
1e610 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
1e620 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 ** INSERT INTO
1e630 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 table1 VALUES('I
1e640 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79 t''s a happy day
1e650 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 !').** </pre></b
1e660 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a lockquote>.**.**
1e670 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 This is correct
1e680 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25 . Had we used %
1e690 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c s instead of %q,
1e6a0 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 the generated S
1e6b0 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 QL.** would have
1e6c0 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 looked like thi
1e6d0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 s:.**.** <blockq
1e6e0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 uote><pre>.** I
1e6f0 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 NSERT INTO table
1e700 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 1 VALUES('It's a
1e710 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a happy day!');.*
1e720 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 * </pre></blockq
1e730 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 uote>.**.** This
1e740 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 second example
1e750 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 is an SQL syntax
1e760 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 error. As a ge
1e770 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 neral rule you s
1e780 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 hould.** always
1e790 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f use %q instead o
1e7a0 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 f %s when insert
1e7b0 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 ing text into a
1e7c0 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a string literal..
1e7d0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f **.** ^(The %Q o
1e7e0 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 ption works like
1e7f0 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c %q except it al
1e800 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 so adds single q
1e810 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 uotes around.**
1e820 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 the outside of t
1e830 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e he total string.
1e840 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 Additionally,
1e850 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 if the parameter
1e860 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d in the.** argum
1e870 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 ent list is a NU
1e880 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 LL pointer, %Q s
1e890 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74 ubstitutes the t
1e8a0 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 ext "NULL" (with
1e8b0 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 out.** single qu
1e8c0 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f otes).)^ So, fo
1e8d0 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 r example, one c
1e8e0 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 ould say:.**.**
1e8f0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
1e900 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c >.** char *zSQL
1e910 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e = sqlite3_mprin
1e920 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 tf("INSERT INTO
1e930 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 table VALUES(%Q)
1e940 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 ", zText);.** s
1e950 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 qlite3_exec(db,
1e960 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a zSQL, 0, 0, 0);.
1e970 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 ** sqlite3_free
1e980 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 (zSQL);.** </pre
1e990 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ></blockquote>.*
1e9a0 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 *.** The code ab
1e9b0 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 ove will render
1e9c0 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 a correct SQL st
1e9d0 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a atement in the z
1e9e0 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 SQL.** variable
1e9f0 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 even if the zTex
1ea00 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 t variable is a
1ea10 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a NULL pointer..**
1ea20 0a 2a 2a 20 5e 28 54 68 65 20 22 25 77 22 20 66 .** ^(The "%w" f
1ea30 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e ormatting option
1ea40 20 69 73 20 6c 69 6b 65 20 22 25 71 22 20 65 78 is like "%q" ex
1ea50 63 65 70 74 20 74 68 61 74 20 69 74 20 65 78 70 cept that it exp
1ea60 65 63 74 73 20 74 6f 0a 2a 2a 20 62 65 20 63 6f ects to.** be co
1ea70 6e 74 61 69 6e 65 64 20 77 69 74 68 69 6e 20 64 ntained within d
1ea80 6f 75 62 6c 65 2d 71 75 6f 74 65 73 20 69 6e 73 ouble-quotes ins
1ea90 74 65 61 64 20 6f 66 20 73 69 6e 67 6c 65 20 71 tead of single q
1eaa0 75 6f 74 65 73 2c 20 61 6e 64 20 69 74 0a 2a 2a uotes, and it.**
1eab0 20 65 73 63 61 70 65 73 20 74 68 65 20 64 6f 75 escapes the dou
1eac0 62 6c 65 2d 71 75 6f 74 65 20 63 68 61 72 61 63 ble-quote charac
1ead0 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 ter instead of t
1eae0 68 65 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65 0a he single-quote.
1eaf0 2a 2a 20 63 68 61 72 61 63 74 65 72 2e 29 5e 20 ** character.)^
1eb00 20 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74 The "%w" format
1eb10 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 69 ting option is i
1eb20 6e 74 65 6e 64 65 64 20 66 6f 72 20 73 61 66 65 ntended for safe
1eb30 6c 79 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 ly inserting.**
1eb40 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e table and column
1eb50 20 6e 61 6d 65 73 20 69 6e 74 6f 20 61 20 63 6f names into a co
1eb60 6e 73 74 72 75 63 74 65 64 20 53 51 4c 20 73 74 nstructed SQL st
1eb70 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e atement..**.** ^
1eb80 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 (The "%z" format
1eb90 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b ting option work
1eba0 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 s like "%s" but
1ebb0 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 with the.** addi
1ebc0 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 tion that after
1ebd0 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 the string has b
1ebe0 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 een read and cop
1ebf0 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 ied into.** the
1ec00 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 result, [sqlite3
1ec10 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c _free()] is call
1ec20 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 ed on the input
1ec30 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 4c string.)^.*/.SQL
1ec40 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 53 51 ITE_API char *SQ
1ec50 4c 49 54 45 5f 43 44 45 43 4c 20 73 71 6c 69 74 LITE_CDECL sqlit
1ec60 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 e3_mprintf(const
1ec70 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c char*,...);.SQL
1ec80 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 53 51 ITE_API char *SQ
1ec90 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
1eca0 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f ite3_vmprintf(co
1ecb0 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 nst char*, va_li
1ecc0 73 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 st);.SQLITE_API
1ecd0 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 43 44 45 char *SQLITE_CDE
1ece0 43 4c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 CL sqlite3_snpri
1ecf0 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f ntf(int,char*,co
1ed00 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b nst char*, ...);
1ed10 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 .SQLITE_API char
1ed20 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c *SQLITE_STDCALL
1ed30 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e sqlite3_vsnprin
1ed40 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e tf(int,char*,con
1ed50 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 st char*, va_lis
1ed60 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
1ed70 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f REF: Memory Allo
1ed80 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d cation Subsystem
1ed90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 .**.** The SQLit
1eda0 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 e core uses thes
1edb0 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 e three routines
1edc0 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 for all of its
1edd0 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 own.** internal
1ede0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
1edf0 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 n needs. "Core"
1ee00 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 in the previous
1ee10 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 sentence.** does
1ee20 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 not include ope
1ee30 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 rating-system sp
1ee40 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 ecific VFS imple
1ee50 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a mentation. The.
1ee60 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 ** Windows VFS u
1ee70 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f ses native mallo
1ee80 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 c() and free() f
1ee90 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f or some operatio
1eea0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ns..**.** ^The s
1eeb0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
1eec0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
1eed0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 a pointer to a b
1eee0 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 lock.** of memor
1eef0 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 y at least N byt
1ef00 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 es in length, wh
1ef10 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 ere N is the par
1ef20 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 ameter..** ^If s
1ef30 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
1ef40 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 is unable to obt
1ef50 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 ain sufficient f
1ef60 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 ree.** memory, i
1ef70 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c t returns a NULL
1ef80 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 pointer. ^If t
1ef90 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 he parameter N t
1efa0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c o.** sqlite3_mal
1efb0 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 loc() is zero or
1efc0 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 negative then s
1efd0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
1efe0 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c returns.** a NUL
1eff0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a L pointer..**.**
1f000 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 ^The sqlite3_ma
1f010 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75 74 69 6e lloc64(N) routin
1f020 65 20 77 6f 72 6b 73 20 6a 75 73 74 20 6c 69 6b e works just lik
1f030 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c e.** sqlite3_mal
1f040 6c 6f 63 28 4e 29 20 65 78 63 65 70 74 20 74 68 loc(N) except th
1f050 61 74 20 4e 20 69 73 20 61 6e 20 75 6e 73 69 67 at N is an unsig
1f060 6e 65 64 20 36 34 2d 62 69 74 20 69 6e 74 65 67 ned 64-bit integ
1f070 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 er instead.** of
1f080 20 61 20 73 69 67 6e 65 64 20 33 32 2d 62 69 74 a signed 32-bit
1f090 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 integer..**.**
1f0a0 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 ^Calling sqlite3
1f0b0 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70 _free() with a p
1f0c0 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c ointer previousl
1f0d0 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 y returned.** by
1f0e0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
1f0f0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 ) or sqlite3_rea
1f100 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 lloc() releases
1f110 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a that memory so.*
1f120 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 * that it might
1f130 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65 be reused. ^The
1f140 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 sqlite3_free()
1f150 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 routine is.** a
1f160 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c no-op if is call
1f170 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 ed with a NULL p
1f180 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 ointer. Passing
1f190 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a a NULL pointer.
1f1a0 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 ** to sqlite3_fr
1f1b0 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 ee() is harmless
1f1c0 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 . After being f
1f1d0 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 reed, memory.**
1f1e0 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 should neither b
1f1f0 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 e read nor writt
1f200 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e en. Even readin
1f210 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 g previously fre
1f220 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 ed.** memory mig
1f230 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 ht result in a s
1f240 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c egmentation faul
1f250 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 t or other sever
1f260 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f e error..** Memo
1f270 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 ry corruption, a
1f280 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 segmentation fa
1f290 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 ult, or other se
1f2a0 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 vere error.** mi
1f2b0 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 ght result if sq
1f2c0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 lite3_free() is
1f2d0 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f called with a no
1f2e0 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 n-NULL pointer t
1f2f0 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f hat.** was not o
1f300 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c btained from sql
1f310 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 ite3_malloc() or
1f320 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
1f330 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ()..**.** ^The s
1f340 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 qlite3_realloc(X
1f350 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 ,N) interface at
1f360 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 tempts to resize
1f370 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f a.** prior memo
1f380 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 ry allocation X
1f390 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e to be at least N
1f3a0 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 bytes..** ^If t
1f3b0 68 65 20 58 20 70 61 72 61 6d 65 74 65 72 20 74 he X parameter t
1f3c0 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f o sqlite3_reallo
1f3d0 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20 61 20 4e c(X,N).** is a N
1f3e0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e ULL pointer then
1f3f0 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 its behavior is
1f400 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 identical to ca
1f410 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 lling.** sqlite3
1f420 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e _malloc(N)..** ^
1f430 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 If the N paramet
1f440 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 er to sqlite3_re
1f450 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73 20 7a 65 alloc(X,N) is ze
1f460 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 ro or.** negativ
1f470 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 e then the behav
1f480 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 ior is exactly t
1f490 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 he same as calli
1f4a0 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 ng.** sqlite3_fr
1f4b0 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 ee(X)..** ^sqlit
1f4c0 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 e3_realloc(X,N)
1f4d0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
1f4e0 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c r to a memory al
1f4f0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 location.** of a
1f500 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 t least N bytes
1f510 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 in size or NULL
1f520 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e 74 20 if insufficient
1f530 6d 65 6d 6f 72 79 20 69 73 20 61 76 61 69 6c 61 memory is availa
1f540 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 ble..** ^If M is
1f550 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 the size of the
1f560 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f prior allocatio
1f570 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 n, then min(N,M)
1f580 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 bytes.** of the
1f590 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f prior allocatio
1f5a0 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 n are copied int
1f5b0 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 o the beginning
1f5c0 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e of buffer return
1f5d0 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 ed.** by sqlite3
1f5e0 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e _realloc(X,N) an
1f5f0 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f d the prior allo
1f600 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e cation is freed.
1f610 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f .** ^If sqlite3_
1f620 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 realloc(X,N) ret
1f630 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 urns NULL and N
1f640 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65 is positive, the
1f650 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f 72 20 61 n the.** prior a
1f660 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 6e 6f 74 llocation is not
1f670 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 freed..**.** ^T
1f680 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c he sqlite3_reall
1f690 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74 65 72 66 oc64(X,N) interf
1f6a0 61 63 65 73 20 77 6f 72 6b 73 20 74 68 65 20 73 aces works the s
1f6b0 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65 ame as.** sqlite
1f6c0 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 3_realloc(X,N) e
1f6d0 78 63 65 70 74 20 74 68 61 74 20 4e 20 69 73 20 xcept that N is
1f6e0 61 20 36 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 a 64-bit unsigne
1f6f0 64 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61 d integer instea
1f700 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d 62 69 74 d.** of a 32-bit
1f710 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 2e signed integer.
1f720 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20 69 73 20 .**.** ^If X is
1f730 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 a memory allocat
1f740 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 6f ion previously o
1f750 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c btained from sql
1f760 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a ite3_malloc(),.*
1f770 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 * sqlite3_malloc
1f780 36 34 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 64(), sqlite3_re
1f790 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73 71 6c 69 alloc(), or sqli
1f7a0 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 2c te3_realloc64(),
1f7b0 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 then.** sqlite3
1f7c0 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e _msize(X) return
1f7d0 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 s the size of th
1f7e0 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 at memory alloca
1f7f0 74 69 6f 6e 20 69 6e 20 62 79 74 65 73 2e 0a 2a tion in bytes..*
1f800 2a 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 * ^The value ret
1f810 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 urned by sqlite3
1f820 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67 68 74 20 _msize(X) might
1f830 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 be larger than t
1f840 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 he number.** of
1f850 62 79 74 65 73 20 72 65 71 75 65 73 74 65 64 20 bytes requested
1f860 77 68 65 6e 20 58 20 77 61 73 20 61 6c 6c 6f 63 when X was alloc
1f870 61 74 65 64 2e 20 20 5e 49 66 20 58 20 69 73 20 ated. ^If X is
1f880 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 a NULL pointer t
1f890 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d hen.** sqlite3_m
1f8a0 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 size(X) returns
1f8b0 7a 65 72 6f 2e 20 20 49 66 20 58 20 70 6f 69 6e zero. If X poin
1f8c0 74 73 20 74 6f 20 73 6f 6d 65 74 68 69 6e 67 20 ts to something
1f8d0 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 that is not.** t
1f8e0 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 he beginning of
1f8f0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
1f900 6e 2c 20 6f 72 20 69 66 20 69 74 20 70 6f 69 6e n, or if it poin
1f910 74 73 20 74 6f 20 61 20 66 6f 72 6d 65 72 6c 79 ts to a formerly
1f920 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d 6f 72 79 .** valid memory
1f930 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 68 61 74 allocation that
1f940 20 68 61 73 20 6e 6f 77 20 62 65 65 6e 20 66 72 has now been fr
1f950 65 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 eed, then the be
1f960 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c havior.** of sql
1f970 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 69 73 ite3_msize(X) is
1f980 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 undefined and p
1f990 6f 73 73 69 62 6c 79 20 68 61 72 6d 66 75 6c 2e ossibly harmful.
1f9a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f .**.** ^The memo
1f9b0 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 ry returned by s
1f9c0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c qlite3_malloc(),
1f9d0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
1f9e0 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d (),.** sqlite3_m
1f9f0 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e 64 20 73 alloc64(), and s
1fa00 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 qlite3_realloc64
1fa10 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 ().** is always
1fa20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 aligned to at le
1fa30 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f ast an 8 byte bo
1fa40 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a undary, or to a.
1fa50 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64 61 ** 4 byte bounda
1fa60 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 ry if the [SQLIT
1fa70 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 E_4_BYTE_ALIGNED
1fa80 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 _MALLOC] compile
1fa90 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 -time.** option
1faa0 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 is used..**.** I
1fab0 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e n SQLite version
1fac0 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 3.5.0 and 3.5.1
1fad0 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c , it was possibl
1fae0 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 e to define.** t
1faf0 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d he SQLITE_OMIT_M
1fb00 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e EMORY_ALLOCATION
1fb10 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 which would cau
1fb20 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a se the built-in.
1fb30 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
1fb40 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 n of these routi
1fb50 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 nes to be omitte
1fb60 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c d. That capabil
1fb70 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e ity.** is no lon
1fb80 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f ger provided. O
1fb90 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d nly built-in mem
1fba0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 ory allocators c
1fbb0 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a an be used..**.*
1fbc0 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 * Prior to SQLit
1fbd0 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 e version 3.7.10
1fbe0 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 , the Windows OS
1fbf0 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 interface layer
1fc00 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 called.** the s
1fc10 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 ystem malloc() a
1fc20 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74 nd free() direct
1fc30 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 ly when converti
1fc40 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 ng.** filenames
1fc50 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d between the UTF-
1fc60 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 8 encoding used
1fc70 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 by SQLite.** and
1fc80 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 whatever filena
1fc90 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 me encoding is u
1fca0 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69 sed by the parti
1fcb0 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a cular Windows.**
1fcc0 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 installation.
1fcd0 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f Memory allocatio
1fce0 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20 64 65 n errors were de
1fcf0 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 tected, but.** t
1fd00 68 65 79 20 77 65 72 65 20 72 65 70 6f 72 74 65 hey were reporte
1fd10 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 d back as [SQLIT
1fd20 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a E_CANTOPEN] or.*
1fd30 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d * [SQLITE_IOERR]
1fd40 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 rather than [SQ
1fd50 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a LITE_NOMEM]..**.
1fd60 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 ** The pointer a
1fd70 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c rguments to [sql
1fd80 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 ite3_free()] and
1fd90 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f [sqlite3_reallo
1fda0 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 c()].** must be
1fdb0 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 either NULL or e
1fdc0 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 lse pointers obt
1fdd0 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 ained from a pri
1fde0 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e or.** invocation
1fdf0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c of [sqlite3_mal
1fe00 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 loc()] or [sqlit
1fe10 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 e3_realloc()] th
1fe20 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 at have.** not y
1fe30 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 et been released
1fe40 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c ..**.** The appl
1fe50 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 ication must not
1fe60 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 read or write a
1fe70 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 ny part of.** a
1fe80 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 block of memory
1fe90 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 after it has bee
1fea0 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67 n released using
1feb0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 .** [sqlite3_fre
1fec0 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 e()] or [sqlite3
1fed0 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a _realloc()]..*/.
1fee0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
1fef0 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 *SQLITE_STDCALL
1ff00 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 sqlite3_malloc(i
1ff10 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 nt);.SQLITE_API
1ff20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 void *SQLITE_STD
1ff30 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 61 6c CALL sqlite3_mal
1ff40 6c 6f 63 36 34 28 73 71 6c 69 74 65 33 5f 75 69 loc64(sqlite3_ui
1ff50 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 nt64);.SQLITE_AP
1ff60 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 I void *SQLITE_S
1ff70 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 TDCALL sqlite3_r
1ff80 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e ealloc(void*, in
1ff90 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 t);.SQLITE_API v
1ffa0 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 oid *SQLITE_STDC
1ffb0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c ALL sqlite3_real
1ffc0 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c loc64(void*, sql
1ffd0 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 53 51 ite3_uint64);.SQ
1ffe0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 LITE_API void SQ
1fff0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
20000 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 ite3_free(void*)
20010 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c ;.SQLITE_API sql
20020 69 74 65 33 5f 75 69 6e 74 36 34 20 53 51 4c 49 ite3_uint64 SQLI
20030 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
20040 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b e3_msize(void*);
20050 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
20060 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 : Memory Allocat
20070 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a or Statistics.**
20080 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 .** SQLite provi
20090 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e des these two in
200a0 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 terfaces for rep
200b0 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 orting on the st
200c0 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b atus.** of the [
200d0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
200e0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ], [sqlite3_free
200f0 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 ()], and [sqlite
20100 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 3_realloc()].**
20110 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 routines, which
20120 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 form the built-i
20130 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 n memory allocat
20140 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a ion subsystem..*
20150 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 *.** ^The [sqlit
20160 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 e3_memory_used()
20170 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ] routine return
20180 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
20190 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f bytes.** of memo
201a0 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 ry currently out
201b0 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 standing (malloc
201c0 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 ed but not freed
201d0 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 )..** ^The [sqli
201e0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 te3_memory_highw
201f0 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 ater()] routine
20200 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 returns the maxi
20210 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 mum.** value of
20220 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f [sqlite3_memory_
20230 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 used()] since th
20240 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 e high-water mar
20250 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 k.** was last re
20260 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 set. ^The value
20270 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 s returned by [s
20280 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 qlite3_memory_us
20290 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 ed()] and.** [sq
202a0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 lite3_memory_hig
202b0 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 hwater()] includ
202c0 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a e any overhead.*
202d0 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 * added by SQLit
202e0 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 e in its impleme
202f0 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 ntation of [sqli
20300 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a te3_malloc()],.*
20310 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 * but not overhe
20320 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20 ad added by the
20330 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 any underlying s
20340 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a ystem library.**
20350 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b routines that [
20360 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
20370 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a ] may call..**.*
20380 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 * ^The memory hi
20390 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 gh-water mark is
203a0 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 reset to the cu
203b0 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a rrent value of.*
203c0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 * [sqlite3_memor
203d0 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 y_used()] if and
203e0 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 only if the par
203f0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 ameter to.** [sq
20400 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 lite3_memory_hig
20410 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 hwater()] is tru
20420 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 e. ^The value r
20430 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 eturned.** by [s
20440 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 qlite3_memory_hi
20450 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 ghwater(1)] is t
20460 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 he high-water ma
20470 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 rk.** prior to t
20480 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c he reset..*/.SQL
20490 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f ITE_API sqlite3_
204a0 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 54 44 int64 SQLITE_STD
204b0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 65 6d CALL sqlite3_mem
204c0 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a ory_used(void);.
204d0 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 SQLITE_API sqlit
204e0 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 45 5f e3_int64 SQLITE_
204f0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
20500 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 memory_highwater
20510 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b (int resetFlag);
20520 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
20530 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 : Pseudo-Random
20540 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 Number Generator
20550 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f .**.** SQLite co
20560 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 ntains a high-qu
20570 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e ality pseudo-ran
20580 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 dom number gener
20590 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 ator (PRNG) used
205a0 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 to.** select ra
205b0 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f ndom [ROWID | RO
205c0 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 WIDs] when inser
205d0 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 ting new records
205e0 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 into a table th
205f0 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 at.** already us
20600 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 es the largest p
20610 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e ossible [ROWID].
20620 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c The PRNG is al
20630 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 so used for.** t
20640 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 he build-in rand
20650 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 om() and randomb
20660 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69 lob() SQL functi
20670 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72 ons. This inter
20680 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 face allows.** a
20690 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 pplications to a
206a0 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50 ccess the same P
206b0 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75 RNG for other pu
206c0 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 rposes..**.** ^A
206d0 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f call to this ro
206e0 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 utine stores N b
206f0 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 ytes of randomne
20700 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 ss into buffer P
20710 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 70 61 72 61 ..** ^The P para
20720 6d 65 74 65 72 20 63 61 6e 20 62 65 20 61 20 4e meter can be a N
20730 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a ULL pointer..**.
20740 2a 2a 20 5e 49 66 20 74 68 69 73 20 72 6f 75 74 ** ^If this rout
20750 69 6e 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e ine has not been
20760 20 70 72 65 76 69 6f 75 73 6c 79 20 63 61 6c 6c previously call
20770 65 64 20 6f 72 20 69 66 20 74 68 65 20 70 72 65 ed or if the pre
20780 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 vious.** call ha
20790 64 20 4e 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e d N less than on
207a0 65 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e e or a NULL poin
207b0 74 65 72 20 66 6f 72 20 50 2c 20 74 68 65 6e 20 ter for P, then
207c0 74 68 65 20 50 52 4e 47 20 69 73 0a 2a 2a 20 73 the PRNG is.** s
207d0 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 eeded using rand
207e0 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 20 omness obtained
207f0 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d from the xRandom
20800 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 0a 2a ness method of.*
20810 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 * the default [s
20820 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
20830 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 ct..** ^If the p
20840 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 revious call to
20850 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61 64 this routine had
20860 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72 20 6d 6f an N of 1 or mo
20870 72 65 20 61 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d re and a.** non-
20880 4e 55 4c 4c 20 50 20 74 68 65 6e 20 74 68 65 20 NULL P then the
20890 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 pseudo-randomnes
208a0 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a s is generated.*
208b0 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 * internally and
208c0 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 without recours
208d0 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 e to the [sqlite
208e0 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 3_vfs] xRandomne
208f0 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f ss.** method..*/
20900 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
20910 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
20920 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 sqlite3_randomne
20930 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a ss(int N, void *
20940 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 P);../*.** CAPI3
20950 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d REF: Compile-Tim
20960 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 e Authorization
20970 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 Callbacks.** MET
20980 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a HOD: sqlite3.**.
20990 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 ** ^This routine
209a0 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 registers an au
209b0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
209c0 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 k with a particu
209d0 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 lar.** [database
209e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 connection], su
209f0 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 pplied in the fi
20a00 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a rst argument..**
20a10 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 ^The authorizer
20a20 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
20a30 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 oked as SQL stat
20a40 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 ements are being
20a50 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 compiled.** by
20a60 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
20a70 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 ()] or its varia
20a80 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 nts [sqlite3_pre
20a90 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b pare_v2()],.** [
20aa0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
20ab0 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 6()] and [sqlite
20ac0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
20ad0 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a ]. ^At various.
20ae0 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 ** points during
20af0 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e the compilation
20b00 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 process, as log
20b10 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 ic is being crea
20b20 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 ted.** to perfor
20b30 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e m various action
20b40 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 s, the authorize
20b50 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e r callback is in
20b60 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 voked to.** see
20b70 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 if those actions
20b80 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e are allowed. ^
20b90 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 The authorizer c
20ba0 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a allback should.*
20bb0 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 * return [SQLITE
20bc0 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 _OK] to allow th
20bd0 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 e action, [SQLIT
20be0 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 E_IGNORE] to dis
20bf0 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 allow the.** spe
20c00 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 cific action but
20c10 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 allow the SQL s
20c20 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 tatement to cont
20c30 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f inue to be.** co
20c40 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 mpiled, or [SQLI
20c50 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 TE_DENY] to caus
20c60 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c e the entire SQL
20c70 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 statement to be
20c80 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 .** rejected wit
20c90 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 h an error. ^If
20ca0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
20cb0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
20cc0 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 .** any value ot
20cd0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 her than [SQLITE
20ce0 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 _IGNORE], [SQLIT
20cf0 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 E_OK], or [SQLIT
20d00 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 E_DENY].** then
20d10 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 the [sqlite3_pre
20d20 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 pare_v2()] or eq
20d30 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 uivalent call th
20d40 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 at triggered.**
20d50 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 the authorizer w
20d60 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e ill fail with an
20d70 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a error message..
20d80 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 **.** When the c
20d90 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 allback returns
20da0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 [SQLITE_OK], tha
20db0 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 t means the oper
20dc0 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 ation.** request
20dd0 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e ed is ok. ^When
20de0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 the callback re
20df0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 turns [SQLITE_DE
20e00 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c NY], the.** [sql
20e10 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
20e20 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 )] or equivalent
20e30 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 call that trigg
20e40 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 ered the.** auth
20e50 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c orizer will fail
20e60 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d with an error m
20e70 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e essage explainin
20e80 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 g that.** access
20e90 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a is denied. .**.
20ea0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 ** ^The first pa
20eb0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 rameter to the a
20ec0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
20ed0 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 ck is a copy of
20ee0 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 the third.** par
20ef0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 ameter to the sq
20f00 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 lite3_set_author
20f10 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 izer() interface
20f20 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 . ^The second pa
20f30 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 rameter.** to th
20f40 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e e callback is an
20f50 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 integer [SQLITE
20f60 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 _COPY | action c
20f70 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 ode] that specif
20f80 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 ies.** the parti
20f90 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 cular action to
20fa0 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e be authorized. ^
20fb0 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 The third throug
20fc0 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 h sixth paramete
20fd0 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c rs.** to the cal
20fe0 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 lback are zero-t
20ff0 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 erminated string
21000 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 s that contain a
21010 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 dditional.** det
21020 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 ails about the a
21030 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 ction to be auth
21040 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 orized..**.** ^I
21050 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 f the action cod
21060 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 e is [SQLITE_REA
21070 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 D].** and the ca
21080 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b llback returns [
21090 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 SQLITE_IGNORE] t
210a0 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 hen the.** [prep
210b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
210c0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e statement is con
210d0 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 structed to subs
210e0 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c titute.** a NULL
210f0 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 value in place
21100 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c of the table col
21110 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 umn that would h
21120 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 ave.** been read
21130 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 if [SQLITE_OK]
21140 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 had been returne
21150 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f d. The [SQLITE_
21160 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 IGNORE].** retur
21170 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f n can be used to
21180 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 deny an untrust
21190 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74 ed user access t
211a0 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 o individual.**
211b0 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 columns of a tab
211c0 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 le..** ^If the a
211d0 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 ction code is [S
211e0 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e QLITE_DELETE] an
211f0 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 d the callback r
21200 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 eturns.** [SQLIT
21210 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 E_IGNORE] then t
21220 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 he [DELETE] oper
21230 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 ation proceeds b
21240 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 ut the.** [trunc
21250 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e ate optimization
21260 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e ] is disabled an
21270 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 d all rows are d
21280 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 eleted individua
21290 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 lly..**.** An au
212a0 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 thorizer is used
212b0 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 when [sqlite3_p
212c0 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 repare | prepari
212d0 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 ng].** SQL state
212e0 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e ments from an un
212f0 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 trusted source,
21300 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 to ensure that t
21310 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
21320 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 s.** do not try
21330 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74 to access data t
21340 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f hey are not allo
21350 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 wed to see, or t
21360 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a hat they do not.
21370 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 ** try to execut
21380 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 e malicious stat
21390 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 ements that dama
213a0 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e ge the database.
213b0 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 For.** example
213c0 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e , an application
213d0 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 may allow a use
213e0 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 r to enter arbit
213f0 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 rary.** SQL quer
21400 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 ies for evaluati
21410 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65 on by a database
21420 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 . But the appli
21430 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e cation does.** n
21440 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 ot want the user
21450 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d to be able to m
21460 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68 ake arbitrary ch
21470 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 anges to the.**
21480 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 database. An au
21490 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 thorizer could t
214a0 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c hen be put in pl
214b0 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a ace while the.**
214c0 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 user-entered SQ
214d0 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 L is being [sqli
214e0 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 te3_prepare | pr
214f0 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 epared] that.**
21500 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 disallows everyt
21510 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c hing except [SEL
21520 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e ECT] statements.
21530 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 .**.** Applicati
21540 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f ons that need to
21550 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f process SQL fro
21560 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 m untrusted sour
21570 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 ces.** might als
21580 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 o consider lower
21590 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d ing resource lim
215a0 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 its using [sqlit
215b0 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 e3_limit()].** a
215c0 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 nd limiting data
215d0 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 base size using
215e0 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f the [max_page_co
215f0 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a unt] [PRAGMA].**
21600 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 in addition to
21610 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 using an authori
21620 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c zer..**.** ^(Onl
21630 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f y a single autho
21640 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 rizer can be in
21650 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 place on a datab
21660 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a ase connection.*
21670 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 * at a time. Ea
21680 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 ch call to sqlit
21690 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 e3_set_authorize
216a0 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a r overrides the.
216b0 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c ** previous call
216c0 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 .)^ ^Disable th
216d0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 e authorizer by
216e0 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c installing a NUL
216f0 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 L callback..** T
21700 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 he authorizer is
21710 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 disabled by def
21720 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ault..**.** The
21730 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
21740 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 ack must not do
21750 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 anything that wi
21760 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 ll modify.** the
21770 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
21780 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 tion that invoke
21790 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 d the authorizer
217a0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f callback..** No
217b0 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 te that [sqlite3
217c0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 _prepare_v2()] a
217d0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 nd [sqlite3_step
217e0 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 ()] both modify
217f0 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 their.** databas
21800 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f e connections fo
21810 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 r the meaning of
21820 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 "modify" in thi
21830 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a s paragraph..**.
21840 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 ** ^When [sqlite
21850 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
21860 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 is used to prepa
21870 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 re a statement,
21880 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 the.** statement
21890 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 might be re-pre
218a0 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 pared during [sq
218b0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 lite3_step()] du
218c0 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d e to a .** schem
218d0 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 a change. Hence
218e0 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f , the applicatio
218f0 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 n should ensure
21900 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 that the.** corr
21910 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 ect authorizer c
21920 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 allback remains
21930 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 in place during
21940 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 the [sqlite3_ste
21950 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 p()]..**.** ^Not
21960 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f e that the autho
21970 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 rizer callback i
21980 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 s invoked only d
21990 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 uring.** [sqlite
219a0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 3_prepare()] or
219b0 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 its variants. A
219c0 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 uthorization is
219d0 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 not.** performed
219e0 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e during statemen
219f0 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 t evaluation in
21a00 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
21a10 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 , unless.** as s
21a20 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 tated in the pre
21a30 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c vious paragraph,
21a40 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 sqlite3_step()
21a50 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 invokes.** sqlit
21a60 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 e3_prepare_v2()
21a70 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73 to reprepare a s
21a80 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 tatement after a
21a90 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a schema change..
21aa0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
21ab0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
21ac0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 sqlite3_set_aut
21ad0 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 horizer(. sqlit
21ae0 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 e3*,. int (*xAu
21af0 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f th)(void*,int,co
21b00 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 nst char*,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 29 2c 0a *,const char*),.
21b30 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 void *pUserDat
21b40 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 a.);../*.** CAPI
21b50 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 3REF: Authorizer
21b60 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a Return Codes.**
21b70 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 .** The [sqlite3
21b80 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 _set_authorizer
21b90 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c | authorizer cal
21ba0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 lback function]
21bb0 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 must.** return e
21bc0 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b ither [SQLITE_OK
21bd0 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 ] or one of thes
21be0 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 e two constants
21bf0 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 in order.** to s
21c00 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 ignal SQLite whe
21c10 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 ther or not the
21c20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 action is permit
21c30 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a ted. See the.**
21c40 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 [sqlite3_set_au
21c50 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f thorizer | autho
21c60 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 rizer documentat
21c70 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f ion] for additio
21c80 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 nal.** informati
21c90 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 on..**.** Note t
21ca0 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 hat SQLITE_IGNOR
21cb0 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 E is also used a
21cc0 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 s a [conflict re
21cd0 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a solution mode].*
21ce0 2a 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 * returned from
21cf0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 the [sqlite3_vta
21d00 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d b_on_conflict()]
21d10 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 interface..*/.#
21d20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 define SQLITE_DE
21d30 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 NY 1 /* Abor
21d40 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d t the SQL statem
21d50 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f ent with an erro
21d60 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c r */.#define SQL
21d70 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f ITE_IGNORE 2 /
21d80 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 * Don't allow ac
21d90 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 cess, but don't
21da0 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f generate an erro
21db0 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 r */../*.** CAPI
21dc0 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 3REF: Authorizer
21dd0 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a Action Codes.**
21de0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 .** The [sqlite3
21df0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 _set_authorizer(
21e00 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 )] interface reg
21e10 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 isters a callbac
21e20 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 k function.** th
21e30 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f at is invoked to
21e40 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 authorize certa
21e50 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 in SQL statement
21e60 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a actions. The.*
21e70 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 * second paramet
21e80 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 er to the callba
21e90 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 ck is an integer
21ea0 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 code that speci
21eb0 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 fies.** what act
21ec0 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 ion is being aut
21ed0 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 horized. These
21ee0 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 are the integer
21ef0 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 action codes tha
21f00 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 t.** the authori
21f10 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 zer callback may
21f20 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a be passed..**.*
21f30 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 * These action c
21f40 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 ode values signi
21f50 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 fy what kind of
21f60 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 operation is to
21f70 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 be.** authorized
21f80 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 . The 3rd and 4
21f90 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f th parameters to
21fa0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 the authorizati
21fb0 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 on.** callback f
21fc0 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 unction will be
21fd0 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 parameters or NU
21fe0 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 LL depending on
21ff0 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a which of these.*
22000 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 * codes is used
22010 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 as the second pa
22020 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 rameter. ^(The
22030 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 5th parameter to
22040 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a the.** authoriz
22050 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 er callback is t
22060 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 he name of the d
22070 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c atabase ("main",
22080 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e "temp",.** etc.
22090 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e ) if applicable.
220a0 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 )^ ^The 6th par
220b0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 ameter to the au
220c0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
220d0 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 k.** is the name
220e0 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f of the inner-mo
220f0 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 st trigger or vi
22100 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f ew that is respo
22110 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 nsible for.** th
22120 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 e access attempt
22130 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 or NULL if this
22140 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 access attempt
22150 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d is directly from
22160 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 .** top-level SQ
22170 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a L code..*/./****
22180 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
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 20 33 72 64 20 2a 2a 2a 2a ******* 3rd ****
221b0 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a ******** 4th ***
221c0 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e ********/.#defin
221d0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
221e0 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31 INDEX 1
221f0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 /* Index Name
22200 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 Table Name
22210 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
22220 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 SQLITE_CREATE_T
22230 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 ABLE 2
22240 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
22250 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
22260 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
22270 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 SQLITE_CREATE_TE
22280 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 MP_INDEX 3
22290 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 /* Index Name
222a0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
222b0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
222c0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d QLITE_CREATE_TEM
222d0 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 P_TABLE 4
222e0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
222f0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
22300 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
22310 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 LITE_CREATE_TEMP
22320 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f _TRIGGER 5 /
22330 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 * Trigger Name
22340 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 Table Name
22350 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
22360 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f ITE_CREATE_TEMP_
22370 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a VIEW 6 /*
22380 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 View Name
22390 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
223a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
223b0 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 TE_CREATE_TRIGGE
223c0 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 R 7 /*
223d0 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 Trigger Name
223e0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
223f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
22400 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 E_CREATE_VIEW
22410 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 8 /* V
22420 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e iew Name N
22430 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
22440 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
22450 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 _DELETE
22460 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 9 /* Ta
22470 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 ble Name NU
22480 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
22490 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
224a0 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 DROP_INDEX
224b0 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 10 /* Ind
224c0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 ex Name Tab
224d0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
224e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
224f0 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 ROP_TABLE
22500 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 11 /* Tabl
22510 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c e Name NULL
22520 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
22530 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
22540 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 OP_TEMP_INDEX
22550 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 12 /* Index
22560 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 Name Table
22570 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
22580 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
22590 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 P_TEMP_TABLE
225a0 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 13 /* Table
225b0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 Name NULL
225c0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
225d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
225e0 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 _TEMP_TRIGGER
225f0 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 14 /* Trigger
22600 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e Name Table N
22610 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
22620 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
22630 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 TEMP_VIEW
22640 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 15 /* View Nam
22650 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 e NULL
22660 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
22670 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 ne SQLITE_DROP_T
22680 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31 RIGGER 1
22690 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 6 /* Trigger N
226a0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d ame Table Nam
226b0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
226c0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 e SQLITE_DROP_VI
226d0 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37 EW 17
226e0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 /* View Name
226f0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
22700 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
22710 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 SQLITE_INSERT
22720 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20 18
22730 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
22740 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
22750 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
22760 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 SQLITE_PRAGMA
22770 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20 19
22780 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 /* Pragma Name
22790 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 1st arg or N
227a0 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ULL */.#define S
227b0 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 QLITE_READ
227c0 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20 20
227d0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
227e0 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 Column Name
227f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
22800 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 LITE_SELECT
22810 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 21 /
22820 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 * NULL
22830 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
22840 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
22850 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 ITE_TRANSACTION
22860 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 22 /*
22870 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 Operation
22880 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
22890 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
228a0 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 TE_UPDATE
228b0 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 23 /*
228c0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
228d0 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 Column Name
228e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
228f0 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20 E_ATTACH
22900 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 24 /* F
22910 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e ilename N
22920 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
22930 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
22940 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20 _DETACH
22950 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 25 /* Da
22960 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 tabase Name NU
22970 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
22980 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
22990 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 ALTER_TABLE
229a0 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 26 /* Dat
229b0 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 abase Name Tab
229c0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
229d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
229e0 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 EINDEX
229f0 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 27 /* Inde
22a00 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c x Name NULL
22a10 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
22a20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e define SQLITE_AN
22a30 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 ALYZE
22a40 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 28 /* Table
22a50 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
22a60 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
22a70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
22a80 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 ATE_VTABLE
22a90 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 29 /* Table
22aa0 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 Name Module
22ab0 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
22ac0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
22ad0 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 _VTABLE
22ae0 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 30 /* Table N
22af0 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 ame Module
22b00 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 Name */.#def
22b10 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 ine SQLITE_FUNCT
22b20 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 ION
22b30 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 31 /* NULL
22b40 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e Function
22b50 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 Name */.#defi
22b60 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f ne SQLITE_SAVEPO
22b70 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33 INT 3
22b80 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 2 /* Operation
22b90 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 Savepoint
22ba0 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e Name */.#defin
22bb0 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 e SQLITE_COPY
22bc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0
22bd0 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 /* No longer
22be0 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 used */.#define
22bf0 53 51 4c 49 54 45 5f 52 45 43 55 52 53 49 56 45 SQLITE_RECURSIVE
22c00 20 20 20 20 20 20 20 20 20 20 20 20 33 33 20 20 33
22c10 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 /* NULL
22c20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
22c30 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 */../*.** CA
22c40 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 PI3REF: Tracing
22c50 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 And Profiling Fu
22c60 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f nctions.** METHO
22c70 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a D: sqlite3.**.**
22c80 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
22c90 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 register callbac
22ca0 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 k functions that
22cb0 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 can be used for
22cc0 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 .** tracing and
22cd0 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 profiling the ex
22ce0 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 ecution of SQL s
22cf0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a tatements..**.**
22d00 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 ^The callback f
22d10 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 unction register
22d20 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 ed by sqlite3_tr
22d30 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 ace() is invoked
22d40 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 at.** various t
22d50 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c imes when an SQL
22d60 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 statement is be
22d70 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 ing run by [sqli
22d80 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 te3_step()]..**
22d90 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 ^The sqlite3_tra
22da0 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 ce() callback is
22db0 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 invoked with a
22dc0 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 UTF-8 rendering
22dd0 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 of the.** SQL st
22de0 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 atement text as
22df0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 the statement fi
22e00 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 rst begins execu
22e10 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 ting..** ^(Addit
22e20 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 ional sqlite3_tr
22e30 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 ace() callbacks
22e40 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 might occur.** a
22e50 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64 s each triggered
22e60 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 subprogram is e
22e70 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c ntered. The cal
22e80 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 lbacks for trigg
22e90 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 ers.** contain a
22ea0 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 UTF-8 SQL comme
22eb0 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 nt that identifi
22ec0 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 es the trigger.)
22ed0 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c ^.**.** The [SQL
22ee0 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c ITE_TRACE_SIZE_L
22ef0 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 IMIT] compile-ti
22f00 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 me option can be
22f10 20 75 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a used to limit.*
22f20 2a 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 * the length of
22f30 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 [bound parameter
22f40 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 ] expansion in t
22f50 68 65 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c he output of sql
22f60 69 74 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a ite3_trace()..**
22f70 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 .** ^The callbac
22f80 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 k function regis
22f90 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 tered by sqlite3
22fa0 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e _profile() is in
22fb0 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 voked.** as each
22fc0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 SQL statement f
22fd0 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 inishes. ^The p
22fe0 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 rofile callback
22ff0 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 contains.** the
23000 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 original stateme
23010 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 nt text and an e
23020 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d stimate of wall-
23030 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 clock time.** of
23040 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 how long that s
23050 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f tatement took to
23060 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 run. ^The prof
23070 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 ile callback.**
23080 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 time is in units
23090 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c of nanoseconds,
230a0 20 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 however the cur
230b0 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 rent implementat
230c0 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 ion.** is only c
230d0 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 apable of millis
230e0 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e econd resolution
230f0 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 so the six leas
23100 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a t significant.**
23110 20 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 digits in the t
23120 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c ime are meaningl
23130 65 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 ess. Future ver
23140 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a sions of SQLite.
23150 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 ** might provide
23160 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 greater resolut
23170 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 ion on the profi
23180 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 ler callback. T
23190 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 he.** sqlite3_pr
231a0 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e ofile() function
231b0 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 is considered e
231c0 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 xperimental and
231d0 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f is.** subject to
231e0 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 change in futur
231f0 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 e versions of SQ
23200 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f Lite..*/.SQLITE_
23210 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 API void *SQLITE
23220 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
23230 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c _trace(sqlite3*,
23240 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 void(*xTrace)(v
23250 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a oid*,const char*
23260 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 ), void*);.SQLIT
23270 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50 E_API SQLITE_EXP
23280 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a ERIMENTAL void *
23290 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
232a0 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 qlite3_profile(s
232b0 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 qlite3*,. void
232c0 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 (*xProfile)(void
232d0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 *,const char*,sq
232e0 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 lite3_uint64), v
232f0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 oid*);../*.** CA
23300 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 PI3REF: Query Pr
23310 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 ogress Callbacks
23320 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
23330 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 te3.**.** ^The s
23340 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f qlite3_progress_
23350 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 handler(D,N,X,P)
23360 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 interface cause
23370 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a s the callback.*
23380 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 * function X to
23390 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f be invoked perio
233a0 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c dically during l
233b0 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c ong running call
233c0 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 s to.** [sqlite3
233d0 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 _exec()], [sqlit
233e0 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b e3_step()] and [
233f0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c sqlite3_get_tabl
23400 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 e()] for.** data
23410 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
23420 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 D. An example u
23430 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 se for this.** i
23440 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b nterface is to k
23450 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65 eep a GUI update
23460 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 d during a large
23470 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 query..**.** ^T
23480 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 he parameter P i
23490 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 s passed through
234a0 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 as the only par
234b0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a ameter to the .*
234c0 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 * callback funct
234d0 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72 ion X. ^The par
234e0 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 20 ameter N is the
234f0 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 approximate numb
23500 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 er of .** [virtu
23510 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 al machine instr
23520 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 uctions] that ar
23530 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77 e evaluated betw
23540 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a een successive.*
23550 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 * invocations of
23560 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e the callback X.
23570 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20 ^If N is less
23580 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 than one then th
23590 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 e progress.** ha
235a0 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62 6c 65 ndler is disable
235b0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 d..**.** ^Only a
235c0 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 single progress
235d0 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 handler may be
235e0 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 defined at one t
235f0 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 ime per.** [data
23600 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
23610 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20 ; setting a new
23620 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 progress handler
23630 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 cancels the.**
23640 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 old one. ^Setti
23650 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20 74 ng parameter X t
23660 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 o NULL disables
23670 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e the progress han
23680 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 dler..** ^The pr
23690 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69 ogress handler i
236a0 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 s also disabled
236b0 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 by setting N to
236c0 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 a value less.**
236d0 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 than 1..**.** ^I
236e0 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 f the progress c
236f0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 allback returns
23700 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 non-zero, the op
23710 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e eration is.** in
23720 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 terrupted. This
23730 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 feature can be
23740 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e used to implemen
23750 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 t a.** "Cancel"
23760 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 button on a GUI
23770 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 progress dialog
23780 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 box..**.** The p
23790 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 rogress handler
237a0 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f callback must no
237b0 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 t do anything th
237c0 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a at will modify.*
237d0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 * the database c
237e0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 onnection that i
237f0 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 nvoked the progr
23800 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 ess handler..**
23810 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 Note that [sqlit
23820 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
23830 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 and [sqlite3_st
23840 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 ep()] both modif
23850 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 y their.** datab
23860 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 ase connections
23870 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 for the meaning
23880 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 of "modify" in t
23890 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a his paragraph..*
238a0 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 *.*/.SQLITE_API
238b0 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 void SQLITE_STDC
238c0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 ALL sqlite3_prog
238d0 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c ress_handler(sql
238e0 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 ite3*, int, int(
238f0 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a *)(void*), void*
23900 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
23910 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 EF: Opening A Ne
23920 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 w Database Conne
23930 63 74 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 ction.** CONSTRU
23940 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a CTOR: sqlite3.**
23950 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 .** ^These routi
23960 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 nes open an SQLi
23970 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 te database file
23980 20 61 73 20 73 70 65 63 69 66 69 65 64 20 62 79 as specified by
23990 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d the .** filenam
239a0 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 e argument. ^The
239b0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 filename argume
239c0 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 nt is interprete
239d0 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a d as UTF-8 for.*
239e0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 * sqlite3_open()
239f0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 and sqlite3_ope
23a00 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 n_v2() and as UT
23a10 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 F-16 in the nati
23a20 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 ve byte.** order
23a30 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 for sqlite3_ope
23a40 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 n16(). ^(A [data
23a50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
23a60 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c handle is usual
23a70 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 ly.** returned i
23a80 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 n *ppDb, even if
23a90 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 an error occurs
23aa0 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 . The only exce
23ab0 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a ption is that.**
23ac0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e if SQLite is un
23ad0 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 able to allocate
23ae0 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 memory to hold
23af0 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 the [sqlite3] ob
23b00 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 ject,.** a NULL
23b10 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 will be written
23b20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 into *ppDb inste
23b30 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 ad of a pointer
23b40 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d to the [sqlite3]
23b50 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 .** object.)^ ^(
23b60 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 If the database
23b70 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f is opened (and/o
23b80 72 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65 r created) succe
23b90 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a ssfully, then.**
23ba0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 [SQLITE_OK] is
23bb0 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 returned. Other
23bc0 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 wise an [error c
23bd0 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 ode] is returned
23be0 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c .)^ ^The.** [sql
23bf0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f ite3_errmsg()] o
23c00 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 r [sqlite3_errms
23c10 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 g16()] routines
23c20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f can be used to o
23c30 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c btain.** an Engl
23c40 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 ish language des
23c50 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 cription of the
23c60 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 error following
23c70 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 a failure of any
23c80 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 .** of the sqlit
23c90 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e e3_open() routin
23ca0 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 es..**.** ^The d
23cb0 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 efault encoding
23cc0 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 66 6f will be UTF-8 fo
23cd0 72 20 64 61 74 61 62 61 73 65 73 20 63 72 65 61 r databases crea
23ce0 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 73 71 6c ted using.** sql
23cf0 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 ite3_open() or s
23d00 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
23d10 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 . ^The default
23d20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 64 61 74 encoding for dat
23d30 61 62 61 73 65 73 0a 2a 2a 20 63 72 65 61 74 65 abases.** create
23d40 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f d using sqlite3_
23d50 6f 70 65 6e 31 36 28 29 20 77 69 6c 6c 20 62 65 open16() will be
23d60 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e UTF-16 in the n
23d70 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 ative byte order
23d80 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 ..**.** Whether
23d90 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 or not an error
23da0 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 occurs when it i
23db0 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 s opened, resour
23dc0 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 ces.** associate
23dd0 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 d with the [data
23de0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
23df0 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 handle should b
23e00 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a e released by.**
23e10 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b passing it to [
23e20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d sqlite3_close()]
23e30 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c when it is no l
23e40 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a onger required..
23e50 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
23e60 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 3_open_v2() inte
23e70 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 rface works like
23e80 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a sqlite3_open().
23e90 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 ** except that i
23ea0 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 t accepts two ad
23eb0 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 ditional paramet
23ec0 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e ers for addition
23ed0 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 al control.** ov
23ee0 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 er the new datab
23ef0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 ase connection.
23f00 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 ^(The flags par
23f10 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c ameter to.** sql
23f20 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 ite3_open_v2() c
23f30 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a an take one of.*
23f40 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 * the following
23f50 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 three values, op
23f60 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 tionally combine
23f70 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b d with the .** [
23f80 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 SQLITE_OPEN_NOMU
23f90 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 TEX], [SQLITE_OP
23fa0 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b EN_FULLMUTEX], [
23fb0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 SQLITE_OPEN_SHAR
23fc0 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 EDCACHE],.** [SQ
23fd0 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 LITE_OPEN_PRIVAT
23fe0 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 ECACHE], and/or
23ff0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 [SQLITE_OPEN_URI
24000 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a ] flags:)^.**.**
24010 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b <dl>.** ^(<dt>[
24020 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
24030 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ONLY]</dt>.** <d
24040 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 d>The database i
24050 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 s opened in read
24060 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 -only mode. If
24070 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 the database doe
24080 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 s not.** already
24090 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 exist, an error
240a0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 is returned.</d
240b0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 d>)^.**.** ^(<dt
240c0 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 >[SQLITE_OPEN_RE
240d0 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a ADWRITE]</dt>.**
240e0 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 <dd>The databas
240f0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 e is opened for
24100 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 reading and writ
24110 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c ing if possible,
24120 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f or reading.** o
24130 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 nly if the file
24140 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 is write protect
24150 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 ed by the operat
24160 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 ing system. In
24170 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 either.** case t
24180 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 he database must
24190 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 already exist,
241a0 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 otherwise an err
241b0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c or is returned.<
241c0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c /dd>)^.**.** ^(<
241d0 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f dt>[SQLITE_OPEN_
241e0 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 READWRITE] | [SQ
241f0 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 LITE_OPEN_CREATE
24200 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 ]</dt>.** <dd>Th
24210 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 e database is op
24220 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 ened for reading
24230 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e and writing, an
24240 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66 0a d is created if.
24250 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 ** it does not a
24260 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 lready exist. Th
24270 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69 is is the behavi
24280 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 or that is alway
24290 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 s used for.** sq
242a0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 lite3_open() and
242b0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 sqlite3_open16(
242c0 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 ).</dd>)^.** </d
242d0 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 l>.**.** If the
242e0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 3rd parameter to
242f0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
24300 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 () is not one of
24310 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 the.** combinat
24320 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 ions shown above
24330 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 optionally comb
24340 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a ined with other.
24350 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ** [SQLITE_OPEN_
24360 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 READONLY | SQLIT
24370 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a E_OPEN_* bits].*
24380 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 * then the behav
24390 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 ior is undefined
243a0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
243b0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d [SQLITE_OPEN_NOM
243c0 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 UTEX] flag is se
243d0 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 t, then the data
243e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a base connection.
243f0 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 ** opens in the
24400 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 multi-thread [th
24410 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 reading mode] as
24420 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e long as the sin
24430 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f gle-thread.** mo
24440 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 de has not been
24450 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 set at compile-t
24460 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d ime or start-tim
24470 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b e. ^If the.** [
24480 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c SQLITE_OPEN_FULL
24490 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 MUTEX] flag is s
244a0 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 et then the data
244b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
244c0 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 opens.** in the
244d0 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 serialized [thre
244e0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 ading mode] unle
244f0 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 ss single-thread
24500 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 was.** previous
24510 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 ly selected at c
24520 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 ompile-time or s
24530 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 tart-time..** ^T
24540 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f he [SQLITE_OPEN_
24550 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 SHAREDCACHE] fla
24560 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 g causes the dat
24570 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
24580 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 to be.** eligib
24590 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 le to use [share
245a0 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 d cache mode], r
245b0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 egardless of whe
245c0 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 ther or not shar
245d0 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 ed.** cache is e
245e0 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 nabled using [sq
245f0 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 lite3_enable_sha
24600 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e red_cache()]. ^
24610 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f The.** [SQLITE_O
24620 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 PEN_PRIVATECACHE
24630 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 ] flag causes th
24640 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
24650 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 ction to not.**
24660 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b participate in [
24670 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 shared cache mod
24680 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 e] even if it is
24690 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 enabled..**.**
246a0 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 ^The fourth para
246b0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
246c0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 _open_v2() is th
246d0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a e name of the.**
246e0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f [sqlite3_vfs] o
246f0 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e bject that defin
24700 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 es the operating
24710 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 system interfac
24720 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 e that.** the ne
24730 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 w database conne
24740 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 ction should use
24750 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 . ^If the fourt
24760 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a h parameter is.*
24770 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 * a NULL pointer
24780 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c then the defaul
24790 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 t [sqlite3_vfs]
247a0 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a object is used..
247b0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 **.** ^If the fi
247c0 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f lename is ":memo
247d0 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 ry:", then a pri
247e0 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 vate, temporary
247f0 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 in-memory databa
24800 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 se.** is created
24810 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 for the connect
24820 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d ion. ^This in-m
24830 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 emory database w
24840 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a ill vanish when.
24850 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ** the database
24860 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c connection is cl
24870 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 osed. Future ve
24880 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
24890 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 might.** make u
248a0 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c se of additional
248b0 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d special filenam
248c0 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 es that begin wi
248d0 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 th the ":" chara
248e0 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 cter..** It is r
248f0 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 ecommended that
24900 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 when a database
24910 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c filename actuall
24920 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 y does begin wit
24930 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 h.** a ":" chara
24940 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 cter you should
24950 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e prefix the filen
24960 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e ame with a pathn
24970 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 ame such as.** "
24980 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 ./" to avoid amb
24990 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 iguity..**.** ^I
249a0 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 f the filename i
249b0 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e s an empty strin
249c0 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 g, then a privat
249d0 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 e, temporary.**
249e0 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 on-disk database
249f0 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 will be created
24a00 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 . ^This private
24a10 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 database will b
24a20 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c e.** automatical
24a30 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f ly deleted as so
24a40 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61 on as the databa
24a50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
24a60 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b closed..**.** [
24a70 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 [URI filenames i
24a80 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 n sqlite3_open()
24a90 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e ]] <h3>URI Filen
24aa0 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 ames</h3>.**.**
24ab0 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d ^If [URI filenam
24ac0 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f e] interpretatio
24ad0 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e n is enabled, an
24ae0 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 d the filename a
24af0 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e rgument.** begin
24b00 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 s with "file:",
24b10 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d then the filenam
24b20 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 e is interpreted
24b30 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a as a URI. ^URI.
24b40 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 ** filename inte
24b50 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e rpretation is en
24b60 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 abled if the [SQ
24b70 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 LITE_OPEN_URI] f
24b80 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e lag is.** set in
24b90 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 the fourth argu
24ba0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f ment to sqlite3_
24bb0 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 open_v2(), or if
24bc0 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 it has.** been
24bd0 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 enabled globally
24be0 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 using the [SQLI
24bf0 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f TE_CONFIG_URI] o
24c00 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a ption with the.*
24c10 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 * [sqlite3_confi
24c20 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 g()] method or b
24c30 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 y the [SQLITE_US
24c40 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 E_URI] compile-t
24c50 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 ime option..** A
24c60 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 s of SQLite vers
24c70 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 ion 3.7.7, URI f
24c80 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 ilename interpre
24c90 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 tation is turned
24ca0 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 off.** by defau
24cb0 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 lt, but future r
24cc0 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 eleases of SQLit
24cd0 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 e might enable U
24ce0 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 RI filename.** i
24cf0 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 nterpretation by
24d00 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 default. See "
24d10 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 [URI filenames]"
24d20 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a for additional.
24d30 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a ** information..
24d40 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 **.** URI filena
24d50 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 20 61 mes are parsed a
24d60 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 ccording to RFC
24d70 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 3986. ^If the UR
24d80 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a I contains an.**
24d90 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e authority, then
24da0 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 it must be eith
24db0 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 er an empty stri
24dc0 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 ng or the string
24dd0 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 .** "localhost"
24de0 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 . ^If the author
24df0 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d ity is not an em
24e00 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c pty string or "l
24e10 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a ocalhost", an .*
24e20 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 * error is retur
24e30 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 ned to the calle
24e40 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 r. ^The fragment
24e50 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 component of a
24e60 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 URI, if .** pres
24e70 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e ent, is ignored.
24e80 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 .**.** ^SQLite u
24e90 73 65 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d ses the path com
24ea0 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 ponent of the UR
24eb0 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 I as the name of
24ec0 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a the disk file.*
24ed0 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 * which contains
24ee0 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e the database. ^
24ef0 49 66 20 74 68 65 20 70 61 74 68 20 62 65 67 69 If the path begi
24f00 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 ns with a '/' ch
24f10 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 aracter, .** the
24f20 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 n it is interpre
24f30 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 ted as an absolu
24f40 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 te path. ^If the
24f50 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 path does not b
24f60 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 egin .** with a
24f70 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 '/' (meaning tha
24f80 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 t the authority
24f90 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 section is omitt
24fa0 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 ed from the URI)
24fb0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 .** then the pat
24fc0 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 h is interpreted
24fd0 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 as a relative p
24fe0 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 ath. .** ^(On wi
24ff0 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 ndows, the first
25000 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e component of an
25010 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a absolute path .
25020 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70 ** is a drive sp
25030 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 ecification (e.g
25040 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a . "C:").)^.**.**
25050 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 [[core URI quer
25060 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a y parameters]].*
25070 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 * The query comp
25080 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d onent of a URI m
25090 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d ay contain param
250a0 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20 69 eters that are i
250b0 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 nterpreted.** ei
250c0 74 68 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 ther by SQLite i
250d0 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b tself, or by a [
250e0 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 VFS | custom VFS
250f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d implementation]
25100 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 ..** SQLite and
25110 69 74 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46 its built-in [VF
25120 53 65 73 5d 20 69 6e 74 65 72 70 72 65 74 20 74 Ses] interpret t
25130 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 he.** following
25140 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 query parameters
25150 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
25160 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 <li> <b>vfs</b
25170 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 >: ^The "vfs" pa
25180 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 rameter may be u
25190 73 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 sed to specify t
251a0 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 he name of.**
251b0 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 a VFS object t
251c0 68 61 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 hat provides the
251d0 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 operating syste
251e0 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 m interface that
251f0 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 should.** b
25200 65 20 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 e used to access
25210 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
25220 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 le on disk. ^If
25230 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 this option is s
25240 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 et to.** an
25250 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 empty string the
25260 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a default VFS obj
25270 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 ect is used. ^Sp
25280 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e ecifying an unkn
25290 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 own.** VFS i
252a0 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 s an error. ^If
252b0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
252c0 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 ) is used and th
252d0 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a e vfs option is.
252e0 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 ** present,
252f0 74 68 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 then the VFS spe
25300 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 cified by the op
25310 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 tion takes prece
25320 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 dence over.**
25330 20 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 the value pass
25340 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 ed as the fourth
25350 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
25360 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e lite3_open_v2().
25370 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 .**.** <li> <b
25380 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 >mode</b>: ^(The
25390 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 mode parameter
253a0 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 may be set to ei
253b0 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c ther "ro", "rw",
253c0 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f .** "rwc", o
253d0 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 r "memory". Atte
253e0 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 mpting to set it
253f0 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 to any other va
25400 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e lue is.** an
25410 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 error)^. .**
25420 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 ^If "ro" is sp
25430 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 ecified, then th
25440 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 e database is op
25450 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e ened for read-on
25460 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 ly .** acces
25470 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 s, just as if th
25480 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 e [SQLITE_OPEN_R
25490 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 EADONLY] flag ha
254a0 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 d been set in th
254b0 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 e .** third
254c0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 argument to sqli
254d0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e te3_open_v2(). ^
254e0 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 If the mode opti
254f0 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a on is set to .**
25500 20 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 "rw", then
25510 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 the database is
25520 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d opened for read-
25530 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 write (but not c
25540 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 reate) .** a
25550 63 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c ccess, as if SQL
25560 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 ITE_OPEN_READWRI
25570 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 TE (but not SQLI
25580 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 TE_OPEN_CREATE)
25590 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e had .** been
255a0 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 set. ^Value "rw
255b0 63 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 c" is equivalent
255c0 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 to setting both
255d0 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f .** SQLITE_
255e0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 OPEN_READWRITE a
255f0 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 nd SQLITE_OPEN_C
25600 52 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 REATE. ^If the
25610 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a mode option is.*
25620 2a 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 * set to "me
25630 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 mory" then a pur
25640 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 e [in-memory dat
25650 61 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 abase] that neve
25660 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f r reads.** o
25670 72 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 r writes from di
25680 73 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 sk is used. ^It
25690 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 is an error to s
256a0 70 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 pecify a value f
256b0 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f or.** the mo
256c0 64 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 de parameter tha
256d0 74 20 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 t is less restri
256e0 63 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 ctive than that
256f0 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 specified by.**
25700 20 20 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 the flags pa
25710 73 73 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 ssed in the thir
25720 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 d parameter to s
25730 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
25740 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c ..**.** <li> <
25750 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 b>cache</b>: ^Th
25760 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 e cache paramete
25770 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 r may be set to
25780 65 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20 either "shared"
25790 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 or.** "priva
257a0 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 te". ^Setting it
257b0 20 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 to "shared" is
257c0 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 equivalent to se
257d0 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 tting the.**
257e0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 SQLITE_OPEN_SHA
257f0 52 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 REDCACHE bit in
25800 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 the flags argume
25810 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 nt passed to.**
25820 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e sqlite3_open
25830 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 _v2(). ^Setting
25840 74 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 the cache parame
25850 74 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 ter to "private"
25860 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 is .** equi
25870 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e valent to settin
25880 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 g the SQLITE_OPE
25890 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62 N_PRIVATECACHE b
258a0 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 it..** ^If s
258b0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
258c0 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 is used and the
258d0 20 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 "cache" paramet
258e0 65 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e er is present in
258f0 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 .** a URI fi
25900 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 lename, its valu
25910 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 e overrides any
25920 62 65 68 61 76 69 6f 72 20 72 65 71 75 65 73 74 behavior request
25930 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a ed by setting.**
25940 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e SQLITE_OPEN
25950 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 _PRIVATECACHE or
25960 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 SQLITE_OPEN_SHA
25970 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a REDCACHE flag..*
25980 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 *.** <li> <b>ps
25990 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f ow</b>: ^The pso
259a0 77 20 70 61 72 61 6d 65 74 65 72 20 69 6e 64 69 w parameter indi
259b0 63 61 74 65 73 20 77 68 65 74 68 65 72 20 6f 72 cates whether or
259c0 20 6e 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 not the.**
259d0 5b 70 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77 [powersafe overw
259e0 72 69 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64 rite] property d
259f0 6f 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 oes or does not
25a00 61 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 apply to the.**
25a10 20 20 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69 storage medi
25a20 61 20 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64 a on which the d
25a30 61 74 61 62 61 73 65 20 66 69 6c 65 20 72 65 73 atabase file res
25a40 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 ides..**.** <li
25a50 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a > <b>nolock</b>:
25a60 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 ^The nolock par
25a70 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c ameter is a bool
25a80 65 61 6e 20 71 75 65 72 79 20 70 61 72 61 6d 65 ean query parame
25a90 74 65 72 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 ter.** which
25aa0 20 69 66 20 73 65 74 20 64 69 73 61 62 6c 65 73 if set disables
25ab0 20 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e file locking in
25ac0 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 rollback journa
25ad0 6c 20 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a l modes. This.*
25ae0 2a 20 20 20 20 20 69 73 20 75 73 65 66 75 6c 20 * is useful
25af0 66 6f 72 20 61 63 63 65 73 73 69 6e 67 20 61 20 for accessing a
25b00 64 61 74 61 62 61 73 65 20 6f 6e 20 61 20 66 69 database on a fi
25b10 6c 65 73 79 73 74 65 6d 20 74 68 61 74 20 64 6f lesystem that do
25b20 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75 es not.** su
25b30 70 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 pport locking.
25b40 43 61 75 74 69 6f 6e 3a 20 20 44 61 74 61 62 61 Caution: Databa
25b50 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69 se corruption mi
25b60 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 74 77 ght result if tw
25b70 6f 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65 o.** or more
25b80 20 70 72 6f 63 65 73 73 65 73 20 77 72 69 74 65 processes write
25b90 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 to the same dat
25ba0 61 62 61 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e abase and any on
25bb0 65 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20 e of those.**
25bc0 20 20 70 72 6f 63 65 73 73 65 73 20 75 73 65 73 processes uses
25bd0 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a nolock=1..**.**
25be0 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 <li> <b>immuta
25bf0 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d ble</b>: ^The im
25c00 6d 75 74 61 62 6c 65 20 70 61 72 61 6d 65 74 65 mutable paramete
25c10 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 r is a boolean q
25c20 75 65 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 uery.** para
25c30 6d 65 74 65 72 20 74 68 61 74 20 69 6e 64 69 63 meter that indic
25c40 61 74 65 73 20 74 68 61 74 20 74 68 65 20 64 61 ates that the da
25c50 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 73 tabase file is s
25c60 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 tored on.**
25c70 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e read-only media.
25c80 20 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c ^When immutabl
25c90 65 20 69 73 20 73 65 74 2c 20 53 51 4c 69 74 65 e is set, SQLite
25ca0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 assumes that th
25cb0 65 0a 2a 2a 20 20 20 20 20 64 61 74 61 62 61 73 e.** databas
25cc0 65 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 e file cannot be
25cd0 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 62 changed, even b
25ce0 79 20 61 20 70 72 6f 63 65 73 73 20 77 69 74 68 y a process with
25cf0 20 68 69 67 68 65 72 0a 2a 2a 20 20 20 20 20 70 higher.** p
25d00 72 69 76 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f rivilege, and so
25d10 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 the database is
25d20 20 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c opened read-onl
25d30 79 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e y and all lockin
25d40 67 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63 68 61 g.** and cha
25d50 6e 67 65 20 64 65 74 65 63 74 69 6f 6e 20 69 73 nge detection is
25d60 20 64 69 73 61 62 6c 65 64 2e 20 20 43 61 75 74 disabled. Caut
25d70 69 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74 68 65 ion: Setting the
25d80 20 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20 immutable.**
25d90 20 20 70 72 6f 70 65 72 74 79 20 6f 6e 20 61 20 property on a
25da0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 database file th
25db0 61 74 20 64 6f 65 73 20 69 6e 20 66 61 63 74 20 at does in fact
25dc0 63 68 61 6e 67 65 20 63 61 6e 20 72 65 73 75 6c change can resul
25dd0 74 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f t.** in inco
25de0 72 72 65 63 74 20 71 75 65 72 79 20 72 65 73 75 rrect query resu
25df0 6c 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 lts and/or [SQLI
25e00 54 45 5f 43 4f 52 52 55 50 54 5d 20 65 72 72 6f TE_CORRUPT] erro
25e10 72 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20 61 rs..** See a
25e20 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43 lso: [SQLITE_IOC
25e30 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a AP_IMMUTABLE]..*
25e40 2a 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c * .** </ul
25e50 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 >.**.** ^Specify
25e60 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 ing an unknown p
25e70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 arameter in the
25e80 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 query component
25e90 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 of a URI is not
25ea0 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 an.** error. Fu
25eb0 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 ture versions of
25ec0 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e SQLite might un
25ed0 64 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f derstand additio
25ee0 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 nal query.** par
25ef0 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b ameters. See "[
25f00 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 query parameters
25f10 20 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 with special me
25f20 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d aning to SQLite]
25f30 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f " for.** additio
25f40 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e nal information.
25f50 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c .**.** [[URI fil
25f60 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d ename examples]]
25f70 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d <h3>URI filenam
25f80 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a e examples</h3>.
25f90 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 **.** <table bor
25fa0 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 der="1" align=ce
25fb0 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 nter cellpadding
25fc0 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 =5>.** <tr><th>
25fd0 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 URI filenames <t
25fe0 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 h> Results.** <t
25ff0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 r><td> file:data
26000 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 .db <td> .**
26010 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 Open the f
26020 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e ile "data.db" in
26030 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 the current dir
26040 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c ectory..** <tr><
26050 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 td> file:/home/f
26060 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a red/data.db<br>.
26070 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 ** file
26080 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 :///home/fred/da
26090 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 ta.db <br> .**
260a0 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c file://l
260b0 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 ocalhost/home/fr
260c0 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 ed/data.db <br>
260d0 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 <td> .**
260e0 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 Open the datab
260f0 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f ase file "/home/
26100 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a fred/data.db"..*
26110 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a * <tr><td> file:
26120 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f //darkstar/home/
26130 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 fred/data.db <td
26140 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 > .** A
26150 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 n error. "darkst
26160 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 ar" is not a rec
26170 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 ognized authorit
26180 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 y..** <tr><td st
26190 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 yle="white-space
261a0 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 :nowrap"> .**
261b0 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 file:///C
261c0 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e :/Documents%20an
261d0 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 d%20Settings/fre
261e0 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 d/Desktop/data.d
261f0 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 b.** <td> Wi
26200 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e ndows only: Open
26210 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e the file "data.
26220 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 db" on fred's de
26230 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a sktop on drive.*
26240 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e * C:. N
26250 6f 74 65 20 74 68 61 74 20 74 68 65 20 25 32 30 ote that the %20
26260 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 escaping in thi
26270 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 s example is not
26280 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 strictly .**
26290 20 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 necessary
262a0 20 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 74 - space charact
262b0 65 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 ers can be used
262c0 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 literally.**
262d0 20 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c in URI fil
262e0 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c enames..** <tr><
262f0 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 td> file:data.db
26300 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 ?mode=ro&cache=p
26310 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 rivate <td> .**
26320 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 Open fi
26330 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 le "data.db" in
26340 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 the current dire
26350 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f ctory for read-o
26360 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 nly access..**
26370 20 20 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 Regardle
26380 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 ss of whether or
26390 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 not shared-cach
263a0 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 e mode is enable
263b0 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 d by.**
263c0 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 default, use a
263d0 70 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a private cache..*
263e0 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a * <tr><td> file:
263f0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e /home/fred/data.
26400 64 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66 db?vfs=unix-dotf
26410 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 ile <td>.**
26420 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 Open file "
26430 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e /home/fred/data.
26440 64 62 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 db". Use the spe
26450 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 64 cial VFS "unix-d
26460 6f 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20 otfile".**
26470 20 20 20 20 74 68 61 74 20 75 73 65 73 20 64 6f that uses do
26480 74 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61 63 65 t-files in place
26490 20 6f 66 20 70 6f 73 69 78 20 61 64 76 69 73 6f of posix adviso
264a0 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c ry locking..** <
264b0 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 tr><td> file:dat
264c0 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e a.db?mode=readon
264d0 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 ly <td> .**
264e0 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 An error. "
264f0 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 readonly" is not
26500 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 a valid option
26510 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 for the "mode" p
26520 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 arameter..** </t
26530 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 able>.**.** ^URI
26540 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 hexadecimal esc
26550 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 ape sequences (%
26560 48 48 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 HH) are supporte
26570 64 20 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 d within the pat
26580 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 h and.** query c
26590 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 omponents of a U
265a0 52 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 RI. A hexadecima
265b0 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 l escape sequenc
265c0 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a e consists of a.
265d0 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 ** percent sign
265e0 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 - "%" - followed
265f0 20 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 by exactly two
26600 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 hexadecimal digi
26610 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e ts .** specifyin
26620 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 g an octet value
26630 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 . ^Before the pa
26640 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 th or query comp
26650 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 onents of a.** U
26660 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 RI filename are
26670 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 interpreted, the
26680 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 y are encoded us
26690 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c ing UTF-8 and al
266a0 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 l .** hexadecima
266b0 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 l escape sequenc
266c0 65 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 es replaced by a
266d0 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e single byte con
266e0 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 taining the.** c
266f0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 orresponding oct
26700 65 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 et. If this proc
26710 65 73 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e ess generates an
26720 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 invalid UTF-8 e
26730 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 ncoding,.** the
26740 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 results are unde
26750 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e fined..**.** <b>
26760 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 Note to Windows
26770 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 users:</b> The
26780 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f encoding used fo
26790 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 r the filename a
267a0 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 rgument.** of sq
267b0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 lite3_open() and
267c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
267d0 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 () must be UTF-8
267e0 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a , not whatever.*
267f0 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 * codepage is cu
26800 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e rrently defined.
26810 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 Filenames cont
26820 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 aining internati
26830 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 onal.** characte
26840 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 rs must be conve
26850 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 rted to UTF-8 pr
26860 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 ior to passing t
26870 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 hem into.** sqli
26880 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 te3_open() or sq
26890 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e lite3_open_v2().
268a0 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 .**.** <b>Note t
268b0 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d o Windows Runtim
268c0 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 e users:</b> Th
268d0 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 e temporary dire
268e0 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 ctory must be se
268f0 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 t.** prior to ca
26900 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 lling sqlite3_op
26910 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f en() or sqlite3_
26920 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 open_v2(). Othe
26930 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a rwise, various.*
26940 2a 20 66 65 61 74 75 72 65 73 20 74 68 61 74 20 * features that
26950 72 65 71 75 69 72 65 20 74 68 65 20 75 73 65 20 require the use
26960 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c of temporary fil
26970 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a es may fail..**.
26980 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
26990 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 lite3_temp_direc
269a0 74 6f 72 79 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f tory].*/.SQLITE_
269b0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 API int SQLITE_S
269c0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f TDCALL sqlite3_o
269d0 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 pen(. const cha
269e0 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f r *filename, /
269f0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e * Database filen
26a00 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 ame (UTF-8) */.
26a10 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 sqlite3 **ppDb
26a20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a /* OUT:
26a30 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c SQLite db handl
26a40 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 e */.);.SQLITE_A
26a50 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 PI int SQLITE_ST
26a60 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 70 DCALL sqlite3_op
26a70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f en16(. const vo
26a80 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 id *filename,
26a90 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 /* Database file
26aa0 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f name (UTF-16) */
26ab0 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 . sqlite3 **ppD
26ac0 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 b /* OU
26ad0 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e T: SQLite db han
26ae0 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 dle */.);.SQLITE
26af0 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f _API int SQLITE_
26b00 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
26b10 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 open_v2(. const
26b20 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c char *filename,
26b30 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 /* Database f
26b40 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 ilename (UTF-8)
26b50 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 */. sqlite3 **p
26b60 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 pDb, /*
26b70 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 OUT: SQLite db h
26b80 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 andle */. int f
26b90 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 lags,
26ba0 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 /* Flags */.
26bb0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 const char *zVf
26bc0 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 s /* Name
26bd0 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 of VFS module t
26be0 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a o use */.);../*.
26bf0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 ** CAPI3REF: Obt
26c00 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55 ain Values For U
26c10 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a RI Parameters.**
26c20 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75 74 .** These are ut
26c30 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 ility routines,
26c40 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d useful to VFS im
26c50 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 plementations, t
26c60 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 hat check.** to
26c70 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61 73 see if a databas
26c80 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52 49 e file was a URI
26c90 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 that contained
26ca0 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72 79 a specific query
26cb0 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 .** parameter,
26cc0 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e and if so obtain
26cd0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 s the value of t
26ce0 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d 65 hat query parame
26cf0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 ter..**.** If F
26d00 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 is the database
26d10 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 filename pointer
26d20 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 passed into the
26d30 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 xOpen() method
26d40 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 of .** a VFS imp
26d50 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e lementation when
26d60 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d the flags param
26d70 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 eter to xOpen()
26d80 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d has one or .** m
26d90 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 ore of the [SQLI
26da0 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 TE_OPEN_URI] or
26db0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 [SQLITE_OPEN_MAI
26dc0 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20 61 N_DB] bits set a
26dd0 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e nd.** P is the n
26de0 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72 79 ame of the query
26df0 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e parameter, then
26e00 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f .** sqlite3_uri_
26e10 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 parameter(F,P) r
26e20 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 eturns the value
26e30 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 of the P.** par
26e40 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78 69 ameter if it exi
26e50 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f sts or a NULL po
26e60 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73 20 inter if P does
26e70 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61 20 not appear as a
26e80 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 .** query parame
26e90 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 ter on F. If P
26ea0 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61 6d is a query param
26eb0 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 eter of F.** has
26ec0 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c no explicit val
26ed0 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 ue, then sqlite3
26ee0 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 _uri_parameter(F
26ef0 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 ,P) returns.** a
26f00 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 pointer to an e
26f10 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a mpty string..**.
26f20 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 ** The sqlite3_u
26f30 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 ri_boolean(F,P,B
26f40 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 ) routine assume
26f50 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62 6f s that P is a bo
26f60 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 olean.** paramet
26f70 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 er and returns t
26f80 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65 rue (1) or false
26f90 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74 (0) according t
26fa0 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f o the value.** o
26fb0 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65 f P. The sqlite
26fc0 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 3_uri_boolean(F,
26fd0 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74 P,B) routine ret
26fe0 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69 66 urns true (1) if
26ff0 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 the.** value of
27000 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 query parameter
27010 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 P is one of "ye
27020 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22 s", "true", or "
27030 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 on" in any.** ca
27040 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c se or if the val
27050 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 ue begins with a
27060 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 non-zero number
27070 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 . The .** sqlit
27080 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 e3_uri_boolean(F
27090 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72 ,P,B) routines r
270a0 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29 eturns false (0)
270b0 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 if the value of
270c0 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 .** query parame
270d0 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 ter P is one of
270e0 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f "no", "false", o
270f0 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 r "off" in any c
27100 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 ase or.** if the
27110 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 value begins wi
27120 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 th a numeric zer
27130 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20 o. If P is not
27140 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d a query.** param
27150 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 eter on F or if
27160 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 the value of P i
27170 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 s does not match
27180 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 any of the.** a
27190 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 bove, then sqlit
271a0 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 e3_uri_boolean(F
271b0 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42 ,P,B) returns (B
271c0 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 !=0)..**.** The
271d0 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 sqlite3_uri_int6
271e0 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 4(F,P,D) routine
271f0 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61 converts the va
27200 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a lue of P into a.
27210 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 ** 64-bit signed
27220 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74 integer and ret
27230 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65 urns that intege
27240 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65 r, or D if P doe
27250 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 s not.** exist.
27260 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 If the value of
27270 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 P is something
27280 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e other than an in
27290 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a teger, then.** z
272a0 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e ero is returned.
272b0 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 .** .** If F is
272c0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 a NULL pointer,
272d0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 then sqlite3_uri
272e0 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 _parameter(F,P)
272f0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 returns NULL and
27300 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f .** sqlite3_uri_
27310 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 boolean(F,P,B) r
27320 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20 eturns B. If F
27330 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f is not a NULL po
27340 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 inter and.** is
27350 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66 not a database f
27360 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 ile pathname poi
27370 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 nter that SQLite
27380 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 passed into the
27390 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 xOpen.** VFS me
273a0 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62 thod, then the b
273b0 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20 ehavior of this
273c0 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66 routine is undef
273d0 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c ined and probabl
273e0 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 y.** undesirable
273f0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
27400 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 const char *SQLI
27410 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
27420 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 e3_uri_parameter
27430 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 (const char *zFi
27440 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 lename, const ch
27450 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 53 51 4c ar *zParam);.SQL
27460 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 ITE_API int SQLI
27470 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
27480 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 e3_uri_boolean(c
27490 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 onst char *zFile
274a0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 , const char *zP
274b0 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 aram, int bDefau
274c0 6c 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 lt);.SQLITE_API
274d0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 53 51 sqlite3_int64 SQ
274e0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
274f0 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 ite3_uri_int64(c
27500 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 onst char*, cons
27510 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 t char*, sqlite3
27520 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a _int64);.../*.**
27530 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 CAPI3REF: Error
27540 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 Codes And Messa
27550 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 ges.** METHOD: s
27560 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 qlite3.**.** ^If
27570 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
27580 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 sqlite3_* API c
27590 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77 all associated w
275a0 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 ith .** [databas
275b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 e connection] D
275c0 66 61 69 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 failed, then the
275d0 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 sqlite3_errcode
275e0 28 44 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a (D) interface.**
275f0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
27600 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 eric [result cod
27610 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 e] or [extended
27620 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 result code] for
27630 20 74 68 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c that.** API cal
27640 6c 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6d 6f 73 l..** If the mos
27650 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c t recent API cal
27660 6c 20 77 61 73 20 73 75 63 63 65 73 73 66 75 6c l was successful
27670 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 ,.** then the re
27680 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 turn value from
27690 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 sqlite3_errcode(
276a0 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a ) is undefined..
276b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
276c0 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 extended_errcode
276d0 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 ().** interface
276e0 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 is the same exce
276f0 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 pt that it alway
27700 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a s returns the .*
27710 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 * [extended resu
27720 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 lt code] even wh
27730 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 en extended resu
27740 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 lt codes are.**
27750 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 disabled..**.**
27760 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 ^The sqlite3_err
27770 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 msg() and sqlite
27780 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 3_errmsg16() ret
27790 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 urn English-lang
277a0 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 uage.** text tha
277b0 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 t describes the
277c0 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 error, as either
277d0 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 UTF-8 or UTF-16
277e0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a respectively..*
277f0 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f * ^(Memory to ho
27800 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 ld the error mes
27810 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d sage string is m
27820 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c anaged internall
27830 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 y..** The applic
27840 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e ation does not n
27850 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f eed to worry abo
27860 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 ut freeing the r
27870 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 esult..** Howeve
27880 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 r, the error str
27890 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 ing might be ove
278a0 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c rwritten or deal
278b0 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 located by.** su
278c0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 bsequent calls t
278d0 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 o other SQLite i
278e0 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f nterface functio
278f0 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ns.)^.**.** ^The
27900 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 sqlite3_errstr(
27910 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
27920 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d rns the English-
27930 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a language text.**
27940 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 that describes
27950 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 the [result code
27960 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 ], as UTF-8..**
27970 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 ^(Memory to hold
27980 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 the error messa
27990 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e ge string is man
279a0 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a aged internally.
279b0 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 ** and must not
279c0 62 65 20 66 72 65 65 64 20 62 79 20 74 68 65 20 be freed by the
279d0 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a application)^..*
279e0 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 *.** When the se
279f0 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 rialized [thread
27a00 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 ing mode] is in
27a10 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 use, it might be
27a20 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 the.** case tha
27a30 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 t a second error
27a40 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 occurs on a sep
27a50 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 arate thread in
27a60 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 between.** the t
27a70 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 ime of the first
27a80 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 error and the c
27a90 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 all to these int
27aa0 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e erfaces..** When
27ab0 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 that happens, t
27ac0 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 he second error
27ad0 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 will be reported
27ae0 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 since these.**
27af0 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 interfaces alway
27b00 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 s report the mos
27b10 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e t recent result.
27b20 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 To avoid.** th
27b30 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 is, each thread
27b40 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 can obtain exclu
27b50 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 sive use of the
27b60 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
27b70 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e tion] D.** by in
27b80 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f voking [sqlite3_
27b90 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 mutex_enter]([sq
27ba0 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 lite3_db_mutex](
27bb0 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e D)) before begin
27bc0 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 ning.** to use D
27bd0 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 and invoking [s
27be0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 qlite3_mutex_lea
27bf0 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f ve]([sqlite3_db_
27c00 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 mutex](D)) after
27c10 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f .** all calls to
27c20 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 the interfaces
27c30 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20 listed here are
27c40 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a completed..**.**
27c50 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 If an interface
27c60 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 fails with SQLI
27c70 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 TE_MISUSE, that
27c80 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 means the interf
27c90 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b ace.** was invok
27ca0 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 ed incorrectly b
27cb0 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f y the applicatio
27cc0 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 n. In that case
27cd0 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 , the.** error c
27ce0 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 ode and message
27cf0 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 may or may not b
27d00 65 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 e set..*/.SQLITE
27d10 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f _API int SQLITE_
27d20 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
27d30 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 errcode(sqlite3
27d40 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 *db);.SQLITE_API
27d50 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
27d60 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 78 74 65 ALL sqlite3_exte
27d70 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c nded_errcode(sql
27d80 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 ite3 *db);.SQLIT
27d90 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 E_API const char
27da0 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c *SQLITE_STDCALL
27db0 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 sqlite3_errmsg(
27dc0 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 sqlite3*);.SQLIT
27dd0 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 E_API const void
27de0 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c *SQLITE_STDCALL
27df0 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 sqlite3_errmsg1
27e00 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 6(sqlite3*);.SQL
27e10 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 ITE_API const ch
27e20 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 ar *SQLITE_STDCA
27e30 4c 4c 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74 LL sqlite3_errst
27e40 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 r(int);../*.** C
27e50 41 50 49 33 52 45 46 3a 20 50 72 65 70 61 72 65 API3REF: Prepare
27e60 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 d Statement Obje
27e70 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 ct.** KEYWORDS:
27e80 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d {prepared statem
27e90 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 ent} {prepared s
27ea0 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a tatements}.**.**
27eb0 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 An instance of
27ec0 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 this object repr
27ed0 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 esents a single
27ee0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 SQL statement th
27ef0 61 74 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20 63 at.** has been c
27f00 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 62 69 6e ompiled into bin
27f10 61 72 79 20 66 6f 72 6d 20 61 6e 64 20 69 73 20 ary form and is
27f20 72 65 61 64 79 20 74 6f 20 62 65 20 65 76 61 6c ready to be eval
27f30 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 uated..**.** Thi
27f40 6e 6b 20 6f 66 20 65 61 63 68 20 53 51 4c 20 73 nk of each SQL s
27f50 74 61 74 65 6d 65 6e 74 20 61 73 20 61 20 73 65 tatement as a se
27f60 70 61 72 61 74 65 20 63 6f 6d 70 75 74 65 72 20 parate computer
27f70 70 72 6f 67 72 61 6d 2e 20 20 54 68 65 0a 2a 2a program. The.**
27f80 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 original SQL te
27f90 78 74 20 69 73 20 73 6f 75 72 63 65 20 63 6f 64 xt is source cod
27fa0 65 2e 20 20 41 20 70 72 65 70 61 72 65 64 20 73 e. A prepared s
27fb0 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 tatement object
27fc0 0a 2a 2a 20 69 73 20 74 68 65 20 63 6f 6d 70 69 .** is the compi
27fd0 6c 65 64 20 6f 62 6a 65 63 74 20 63 6f 64 65 2e led object code.
27fe0 20 20 41 6c 6c 20 53 51 4c 20 6d 75 73 74 20 62 All SQL must b
27ff0 65 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f e converted into
28000 20 61 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 a.** prepared s
28010 74 61 74 65 6d 65 6e 74 20 62 65 66 6f 72 65 20 tatement before
28020 69 74 20 63 61 6e 20 62 65 20 72 75 6e 2e 0a 2a it can be run..*
28030 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 2d 63 79 *.** The life-cy
28040 63 6c 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 cle of a prepare
28050 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 d statement obje
28060 63 74 20 75 73 75 61 6c 6c 79 20 67 6f 65 73 20 ct usually goes
28070 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a like this:.**.**
28080 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 <ol>.** <li> Cr
28090 65 61 74 65 20 74 68 65 20 70 72 65 70 61 72 65 eate the prepare
280a0 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 d statement obje
280b0 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ct using [sqlite
280c0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2e 3_prepare_v2()].
280d0 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 .** <li> Bind va
280e0 6c 75 65 73 20 74 6f 20 5b 70 61 72 61 6d 65 74 lues to [paramet
280f0 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 ers] using the s
28100 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a qlite3_bind_*().
28110 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 ** interfac
28120 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 es..** <li> Run
28130 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 the SQL by calli
28140 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 ng [sqlite3_step
28150 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 ()] one or more
28160 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 times..** <li> R
28170 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 eset the prepare
28180 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e d statement usin
28190 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 g [sqlite3_reset
281a0 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b ()] then go back
281b0 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 .** to step
281c0 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 2. Do this zer
281d0 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e o or more times.
281e0 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 .** <li> Destroy
281f0 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e the object usin
28200 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c g [sqlite3_final
28210 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e ize()]..** </ol>
28220 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
28230 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 ct sqlite3_stmt
28240 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f sqlite3_stmt;../
28250 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
28260 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a un-time Limits.*
28270 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
28280 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 3.**.** ^(This i
28290 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 nterface allows
282a0 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 the size of vari
282b0 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 ous constructs t
282c0 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 o be limited.**
282d0 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 on a connection
282e0 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 by connection ba
282f0 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 sis. The first
28300 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 parameter is the
28310 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
28320 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 nnection] whose
28330 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 limit is to be s
28340 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 et or queried.
28350 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 The.** second pa
28360 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f rameter is one o
28370 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 f the [limit cat
28380 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 egories] that de
28390 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 fine a.** class
283a0 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f of constructs to
283b0 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 be size limited
283c0 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72 . The third par
283d0 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a ameter is the.**
283e0 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 new limit for t
283f0 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e hat construct.)^
28400 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e .**.** ^If the n
28410 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 ew limit is a ne
28420 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 gative number, t
28430 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 he limit is unch
28440 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 anged..** ^(For
28450 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67 each limit categ
28460 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ory SQLITE_LIMIT
28470 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 _<i>NAME</i> the
28480 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d re is a .** [lim
28490 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72 its | hard upper
284a0 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 bound].** set a
284b0 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 t compile-time b
284c0 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73 73 y a C preprocess
284d0 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a or macro called.
284e0 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c ** [limits | SQL
284f0 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c ITE_MAX_<i>NAME<
28500 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f /i>]..** (The "_
28510 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e LIMIT_" in the n
28520 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 ame is changed t
28530 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a o "_MAX_".))^.**
28540 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e ^Attempts to in
28550 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 crease a limit a
28560 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70 bove its hard up
28570 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a per bound are.**
28580 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 silently trunca
28590 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 ted to the hard
285a0 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a upper bound..**.
285b0 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f ** ^Regardless o
285c0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 f whether or not
285d0 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63 the limit was c
285e0 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 hanged, the .**
285f0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 [sqlite3_limit()
28600 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ] interface retu
28610 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76 61 rns the prior va
28620 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 lue of the limit
28630 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 ..** ^Hence, to
28640 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 find the current
28650 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 value of a limi
28660 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69 t without changi
28670 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 ng it,.** simply
28680 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 invoke this int
28690 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65 20 erface with the
286a0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
286b0 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a set to -1..**.**
286c0 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 Run-time limits
286d0 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f are intended fo
286e0 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 r use in applica
286f0 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 tions that manag
28700 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 e.** both their
28710 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 own internal dat
28720 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 abase and also d
28730 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72 atabases that ar
28740 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 e controlled.**
28750 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 by untrusted ext
28760 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 ernal sources.
28770 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 An example appli
28780 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 cation might be
28790 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 a.** web browser
287a0 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 that has its ow
287b0 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 n databases for
287c0 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 storing history
287d0 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 and.** separate
287e0 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f databases contro
287f0 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 lled by JavaScri
28800 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 pt applications
28810 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 downloaded.** of
28820 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 f the Internet.
28830 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 The internal da
28840 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 tabases can be g
28850 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 iven the.** larg
28860 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 e, default limit
28870 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 s. Databases ma
28880 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 naged by externa
28890 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a l sources can.**
288a0 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 be given much s
288b0 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 maller limits de
288c0 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e signed to preven
288d0 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 t a denial of se
288e0 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e rvice.** attack.
288f0 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 Developers mig
28900 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 ht also want to
28910 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 use the [sqlite3
28920 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 _set_authorizer(
28930 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 )].** interface
28940 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 to further contr
28950 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c ol untrusted SQL
28960 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 . The size of t
28970 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 he database.** c
28980 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 reated by an unt
28990 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61 rusted script ca
289a0 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 n be contained u
289b0 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 sing the.** [max
289c0 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 _page_count] [PR
289d0 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 AGMA]..**.** New
289e0 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 run-time limit
289f0 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 categories may b
28a00 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 e added in futur
28a10 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 53 e releases..*/.S
28a20 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 QLITE_API int SQ
28a30 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
28a40 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 ite3_limit(sqlit
28a50 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 e3*, int id, int
28a60 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a newVal);../*.**
28a70 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 CAPI3REF: Run-T
28a80 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f ime Limit Catego
28a90 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 ries.** KEYWORDS
28aa0 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 : {limit categor
28ab0 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 y} {*limit categ
28ac0 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 ories}.**.** The
28ad0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 se constants def
28ae0 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 ine various perf
28af0 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a ormance limits.*
28b00 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f * that can be lo
28b10 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d wered at run-tim
28b20 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 e using [sqlite3
28b30 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 _limit()]..** Th
28b40 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 e synopsis of th
28b50 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 e meanings of th
28b60 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 e various limits
28b70 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e is shown below.
28b80 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 .** Additional i
28b90 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 nformation is av
28ba0 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 ailable at [limi
28bb0 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 ts | Limits in S
28bc0 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 QLite]..**.** <d
28bd0 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c l>.** [[SQLITE_L
28be0 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 IMIT_LENGTH]] ^(
28bf0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
28c00 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 _LENGTH</dt>.**
28c10 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
28c20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 size of any stri
28c30 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 ng or BLOB or ta
28c40 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 ble row, in byte
28c50 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b s.<dd>)^.**.** [
28c60 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 [SQLITE_LIMIT_SQ
28c70 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 L_LENGTH]] ^(<dt
28c80 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 >SQLITE_LIMIT_SQ
28c90 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a L_LENGTH</dt>.**
28ca0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
28cb0 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 length of an SQ
28cc0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 L statement, in
28cd0 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a bytes.</dd>)^.**
28ce0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d .** [[SQLITE_LIM
28cf0 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 IT_COLUMN]] ^(<d
28d00 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 t>SQLITE_LIMIT_C
28d10 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 OLUMN</dt>.** <d
28d20 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 d>The maximum nu
28d30 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 mber of columns
28d40 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e in a table defin
28d50 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a ition or in the.
28d60 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 ** result set of
28d70 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 a [SELECT] or t
28d80 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 he maximum numbe
28d90 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 r of columns in
28da0 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 an index.** or i
28db0 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 n an ORDER BY or
28dc0 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 GROUP BY clause
28dd0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b .</dd>)^.**.** [
28de0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 [SQLITE_LIMIT_EX
28df0 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 PR_DEPTH]] ^(<dt
28e00 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 >SQLITE_LIMIT_EX
28e10 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a PR_DEPTH</dt>.**
28e20 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
28e30 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 depth of the pa
28e40 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 rse tree on any
28e50 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e expression.</dd>
28e60 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 )^.**.** [[SQLIT
28e70 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 E_LIMIT_COMPOUND
28e80 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e _SELECT]] ^(<dt>
28e90 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d SQLITE_LIMIT_COM
28ea0 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 POUND_SELECT</dt
28eb0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
28ec0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 imum number of t
28ed0 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 erms in a compou
28ee0 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d nd SELECT statem
28ef0 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a ent.</dd>)^.**.*
28f00 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 * [[SQLITE_LIMIT
28f10 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 _VDBE_OP]] ^(<dt
28f20 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 >SQLITE_LIMIT_VD
28f30 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 BE_OP</dt>.** <d
28f40 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 d>The maximum nu
28f50 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 mber of instruct
28f60 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 ions in a virtua
28f70 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 l machine progra
28f80 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 m.** used to imp
28f90 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 lement an SQL st
28fa0 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c atement. This l
28fb0 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72 imit is not curr
28fc0 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 ently.** enforce
28fd0 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d d, though that m
28fe0 69 67 68 74 20 62 65 20 61 64 64 65 64 20 69 6e ight be added in
28ff0 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c some future rel
29000 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 ease of.** SQLit
29010 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 e.</dd>)^.**.**
29020 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 [[SQLITE_LIMIT_F
29030 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 UNCTION_ARG]] ^(
29040 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
29050 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 _FUNCTION_ARG</d
29060 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
29070 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
29080 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 arguments on a f
29090 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a unction.</dd>)^.
290a0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c **.** [[SQLITE_L
290b0 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 IMIT_ATTACHED]]
290c0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d ^(<dt>SQLITE_LIM
290d0 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e IT_ATTACHED</dt>
290e0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
290f0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 mum number of [A
29100 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 TTACH | attached
29110 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f databases].)^</
29120 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
29130 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 TE_LIMIT_LIKE_PA
29140 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a TTERN_LENGTH]].*
29150 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c * ^(<dt>SQLITE_L
29160 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 IMIT_LIKE_PATTER
29170 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a N_LENGTH</dt>.**
29180 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
29190 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 length of the p
291a0 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 attern argument
291b0 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 to the [LIKE] or
291c0 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 .** [GLOB] opera
291d0 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a tors.</dd>)^.**.
291e0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ** [[SQLITE_LIMI
291f0 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 T_VARIABLE_NUMBE
29200 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c R]].** ^(<dt>SQL
29210 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 ITE_LIMIT_VARIAB
29220 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a LE_NUMBER</dt>.*
29230 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
29240 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f m index number o
29250 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 f any [parameter
29260 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 ] in an SQL stat
29270 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b ement.)^.**.** [
29280 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 [SQLITE_LIMIT_TR
29290 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 IGGER_DEPTH]] ^(
292a0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
292b0 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f _TRIGGER_DEPTH</
292c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
292d0 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 aximum depth of
292e0 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 recursion for tr
292f0 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a iggers.</dd>)^.*
29300 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 *.** [[SQLITE_LI
29310 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 MIT_WORKER_THREA
29320 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 DS]] ^(<dt>SQLIT
29330 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 E_LIMIT_WORKER_T
29340 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c HREADS</dt>.** <
29350 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e dd>The maximum n
29360 75 6d 62 65 72 20 6f 66 20 61 75 78 69 6c 69 61 umber of auxilia
29370 72 79 20 77 6f 72 6b 65 72 20 74 68 72 65 61 64 ry worker thread
29380 73 20 74 68 61 74 20 61 20 73 69 6e 67 6c 65 0a s that a single.
29390 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ** [prepared sta
293a0 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 tement] may star
293b0 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 t.</dd>)^.** </d
293c0 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 l>.*/.#define SQ
293d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 LITE_LIMIT_LENGT
293e0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 H
293f0 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 0.#define S
29400 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f QLITE_LIMIT_SQL_
29410 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 LENGTH
29420 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 1.#define
29430 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c SQLITE_LIMIT_COL
29440 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 UMN
29450 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 2.#define
29460 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 SQLITE_LIMIT_EX
29470 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 PR_DEPTH
29480 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 3.#defin
29490 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 e SQLITE_LIMIT_C
294a0 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 OMPOUND_SELECT
294b0 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 4.#defi
294c0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
294d0 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 VDBE_OP
294e0 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 5.#def
294f0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
29500 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 _FUNCTION_ARG
29510 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 6.#de
29520 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
29530 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20 T_ATTACHED
29540 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 7.#d
29550 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
29560 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f IT_LIKE_PATTERN_
29570 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 LENGTH 8.#
29580 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
29590 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d MIT_VARIABLE_NUM
295a0 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a BER 9.
295b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
295c0 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 IMIT_TRIGGER_DEP
295d0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30 TH 10
295e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
295f0 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 LIMIT_WORKER_THR
29600 45 41 44 53 20 20 20 20 20 20 20 20 20 20 20 31 EADS 1
29610 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 1../*.** CAPI3RE
29620 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 F: Compiling An
29630 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a SQL Statement.**
29640 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 KEYWORDS: {SQL
29650 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c statement compil
29660 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 er}.** METHOD: s
29670 71 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 qlite3.** CONSTR
29680 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 UCTOR: sqlite3_s
29690 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 tmt.**.** To exe
296a0 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 cute an SQL quer
296b0 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 y, it must first
296c0 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 be compiled int
296d0 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a o a byte-code.**
296e0 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f program using o
296f0 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 ne of these rout
29700 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ines..**.** The
29710 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 first argument,
29720 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 "db", is a [data
29730 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
29740 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 obtained from a
29750 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 .** prior succes
29760 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 sful call to [sq
29770 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b lite3_open()], [
29780 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
29790 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 )] or.** [sqlite
297a0 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 3_open16()]. Th
297b0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
297c0 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 ction must not h
297d0 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e ave been closed.
297e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e .**.** The secon
297f0 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 d argument, "zSq
29800 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 l", is the state
29810 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 ment to be compi
29820 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 led, encoded.**
29830 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 as either UTF-8
29840 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 or UTF-16. The
29850 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 sqlite3_prepare(
29860 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 ) and sqlite3_pr
29870 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e epare_v2().** in
29880 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 terfaces use UTF
29890 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f -8, and sqlite3_
298a0 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 prepare16() and
298b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
298c0 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 6_v2().** use UT
298d0 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 F-16..**.** ^If
298e0 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 the nByte argume
298f0 6e 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 nt is negative,
29900 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 then zSql is rea
29910 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 d up to the.** f
29920 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e irst zero termin
29930 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 ator. ^If nByte
29940 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65 is positive, the
29950 6e 20 69 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e n it is the.** n
29960 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 72 umber of bytes r
29970 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 ead from zSql.
29980 5e 49 66 20 6e 42 79 74 65 20 69 73 20 7a 65 72 ^If nByte is zer
29990 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 72 65 70 61 o, then no prepa
299a0 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 red.** statement
299b0 20 69 73 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a is generated..*
299c0 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 * If the caller
299d0 6b 6e 6f 77 73 20 74 68 61 74 20 74 68 65 20 73 knows that the s
299e0 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 upplied string i
299f0 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 s nul-terminated
29a00 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 , then.** there
29a10 69 73 20 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f is a small perfo
29a20 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 rmance advantage
29a30 20 74 6f 20 70 61 73 73 69 6e 67 20 61 6e 20 6e to passing an n
29a40 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 Byte parameter t
29a50 68 61 74 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 hat.** is the nu
29a60 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e mber of bytes in
29a70 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e the input strin
29a80 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f g <i>including</
29a90 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 i>.** the nul-te
29aa0 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 rminator..**.**
29ab0 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f ^If pzTail is no
29ac0 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 t NULL then *pzT
29ad0 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 ail is made to p
29ae0 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 oint to the firs
29af0 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 t byte.** past t
29b00 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 he end of the fi
29b10 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e rst SQL statemen
29b20 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 t in zSql. Thes
29b30 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a e routines only.
29b40 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 ** compile the f
29b50 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 irst statement i
29b60 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 n zSql, so *pzTa
29b70 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 il is left point
29b80 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 ing to.** what r
29b90 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 emains uncompile
29ba0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d d..**.** ^*ppStm
29bb0 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 t is left pointi
29bc0 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 ng to a compiled
29bd0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
29be0 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 ment] that can b
29bf0 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 e.** executed us
29c00 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 ing [sqlite3_ste
29c10 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 p()]. ^If there
29c20 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 is an error, *p
29c30 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 pStmt is set.**
29c40 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 to NULL. ^If th
29c50 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e e input text con
29c60 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 tains no SQL (if
29c70 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e the input is an
29c80 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 empty.** string
29c90 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 or a comment) t
29ca0 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 hen *ppStmt is s
29cb0 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 et to NULL..** T
29cc0 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 he calling proce
29cd0 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 dure is responsi
29ce0 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 ble for deleting
29cf0 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a the compiled.**
29d00 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 SQL statement u
29d10 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 sing [sqlite3_fi
29d20 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 nalize()] after
29d30 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 it has finished
29d40 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 with it..** ppSt
29d50 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 mt may not be NU
29d60 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 LL..**.** ^On su
29d70 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 ccess, the sqlit
29d80 65 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d e3_prepare() fam
29d90 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 ily of routines
29da0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f return [SQLITE_O
29db0 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 K];.** otherwise
29dc0 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d an [error code]
29dd0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
29de0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
29df0 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 prepare_v2() and
29e00 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
29e10 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 16_v2() interfac
29e20 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d es are.** recomm
29e30 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 ended for all ne
29e40 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 w programs. The
29e50 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 two older interf
29e60 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 aces are retaine
29e70 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 d.** for backwar
29e80 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 ds compatibility
29e90 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20 , but their use
29ea0 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a is discouraged..
29eb0 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 ** ^In the "v2"
29ec0 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 interfaces, the
29ed0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
29ee0 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 nt.** that is re
29ef0 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c turned (the [sql
29f00 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 ite3_stmt] objec
29f10 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f t) contains a co
29f20 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 py of the.** ori
29f30 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 ginal SQL text.
29f40 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20 This causes the
29f50 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
29f60 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a interface to.**
29f70 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e behave differen
29f80 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 tly in three way
29f90 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a s:.**.** <ol>.**
29fa0 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 <li>.** ^If the
29fb0 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 database schema
29fc0 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 changes, instea
29fd0 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b d of returning [
29fe0 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 SQLITE_SCHEMA] a
29ff0 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 s it.** always u
2a000 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 sed to do, [sqli
2a010 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c te3_step()] will
2a020 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 automatically r
2a030 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c ecompile the SQL
2a040 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e .** statement an
2a050 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 d try to run it
2a060 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 again. As many a
2a070 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 s [SQLITE_MAX_SC
2a080 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 HEMA_RETRY].** r
2a090 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 etries will occu
2a0a0 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 r before sqlite3
2a0b0 5f 73 74 65 70 28 29 20 67 69 76 65 73 20 75 70 _step() gives up
2a0c0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20 and returns an
2a0d0 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a error..** </li>.
2a0e0 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 **.** <li>.** ^W
2a0f0 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 hen an error occ
2a100 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 urs, [sqlite3_st
2a110 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 ep()] will retur
2a120 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 n one of the det
2a130 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 ailed.** [error
2a140 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e codes] or [exten
2a150 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d ded error codes]
2a160 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 . ^The legacy b
2a170 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 ehavior was that
2a180 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 .** [sqlite3_ste
2a190 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 p()] would only
2a1a0 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 return a generic
2a1b0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
2a1c0 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 result code.** a
2a1d0 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 nd the applicati
2a1e0 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f on would have to
2a1f0 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 make a second c
2a200 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
2a210 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f reset()].** in o
2a220 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 rder to find the
2a230 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 underlying caus
2a240 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d e of the problem
2a250 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 . With the "v2"
2a260 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 prepare.** inter
2a270 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 faces, the under
2a280 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 lying reason for
2a290 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 the error is re
2a2a0 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 turned immediate
2a2b0 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a ly..** </li>.**.
2a2c0 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 ** <li>.** ^If t
2a2d0 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 he specific valu
2a2e0 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 e bound to [para
2a2f0 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 meter | host par
2a300 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a ameter] in the .
2a310 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 ** WHERE clause
2a320 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 might influence
2a330 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 the choice of qu
2a340 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 ery plan for a s
2a350 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 tatement,.** the
2a360 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 n the statement
2a370 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 will be automati
2a380 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 cally recompiled
2a390 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61 , as if there ha
2a3a0 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 d been .** a sch
2a3b0 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 ema change, on t
2a3c0 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 he first [sqlit
2a3d0 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 e3_step()] call
2a3e0 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 following any ch
2a3f0 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b ange.** to the [
2a400 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
2a410 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 t | bindings] of
2a420 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 that [parameter
2a430 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 ]. .** ^The spec
2a440 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 ific value of WH
2a450 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 ERE-clause [para
2a460 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 meter] might inf
2a470 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 luence the .** c
2a480 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 hoice of query p
2a490 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d lan if the param
2a4a0 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 eter is the left
2a4b0 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 -hand side of a
2a4c0 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c [LIKE].** or [GL
2a4d0 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 OB] operator or
2a4e0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 if the parameter
2a4f0 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 is compared to
2a500 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d an indexed colum
2a510 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 n.** and the [SQ
2a520 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 LITE_ENABLE_STAT
2a530 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 3] compile-time
2a540 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 option is enable
2a550 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c d..** </li>.** <
2a560 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 /ol>.*/.SQLITE_A
2a570 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 PI int SQLITE_ST
2a580 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 DCALL sqlite3_pr
2a590 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 epare(. sqlite3
2a5a0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 *db,
2a5b0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e /* Database han
2a5c0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 dle */. const c
2a5d0 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 har *zSql,
2a5e0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e /* SQL statemen
2a5f0 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 t, UTF-8 encoded
2a600 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c */. int nByte,
2a610 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
2a620 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 Maximum length
2a630 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 of zSql in bytes
2a640 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 . */. sqlite3_s
2a650 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f tmt **ppStmt, /
2a660 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 * OUT: Statement
2a670 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
2a680 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c st char **pzTail
2a690 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 /* OUT: Poi
2a6a0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 nter to unused p
2a6b0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a ortion of zSql *
2a6c0 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 /.);.SQLITE_API
2a6d0 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 int SQLITE_STDCA
2a6e0 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 LL sqlite3_prepa
2a6f0 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 re_v2(. sqlite3
2a700 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 *db,
2a710 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e /* Database han
2a720 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 dle */. const c
2a730 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 har *zSql,
2a740 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e /* SQL statemen
2a750 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 t, UTF-8 encoded
2a760 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c */. int nByte,
2a770 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
2a780 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 Maximum length
2a790 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 of zSql in bytes
2a7a0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 . */. sqlite3_s
2a7b0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f tmt **ppStmt, /
2a7c0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 * OUT: Statement
2a7d0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
2a7e0 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c st char **pzTail
2a7f0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 /* OUT: Poi
2a800 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 nter to unused p
2a810 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a ortion of zSql *
2a820 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 /.);.SQLITE_API
2a830 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 int SQLITE_STDCA
2a840 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 LL sqlite3_prepa
2a850 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 re16(. sqlite3
2a860 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 *db,
2a870 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 /* Database hand
2a880 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f le */. const vo
2a890 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 id *zSql,
2a8a0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 /* SQL statement
2a8b0 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 , UTF-16 encoded
2a8c0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c */. int nByte,
2a8d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
2a8e0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 Maximum length
2a8f0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 of zSql in bytes
2a900 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 . */. sqlite3_s
2a910 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f tmt **ppStmt, /
2a920 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 * OUT: Statement
2a930 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
2a940 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c st void **pzTail
2a950 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 /* OUT: Poi
2a960 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 nter to unused p
2a970 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a ortion of zSql *
2a980 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 /.);.SQLITE_API
2a990 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 int SQLITE_STDCA
2a9a0 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 LL sqlite3_prepa
2a9b0 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 re16_v2(. sqlit
2a9c0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 e3 *db,
2a9d0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 /* Database h
2a9e0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
2a9f0 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 void *zSql,
2aa00 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d /* SQL statem
2aa10 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f ent, UTF-16 enco
2aa20 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 ded */. int nBy
2aa30 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 te,
2aa40 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 /* Maximum leng
2aa50 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 th of zSql in by
2aa60 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 tes. */. sqlite
2aa70 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 3_stmt **ppStmt,
2aa80 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d /* OUT: Statem
2aa90 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 ent handle */.
2aaa0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 const void **pzT
2aab0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 ail /* OUT:
2aac0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 Pointer to unuse
2aad0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 d portion of zSq
2aae0 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 l */.);../*.** C
2aaf0 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 API3REF: Retriev
2ab00 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 ing Statement SQ
2ab10 4c 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c L.** METHOD: sql
2ab20 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 ite3_stmt.**.**
2ab30 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 ^This interface
2ab40 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 can be used to r
2ab50 65 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20 etrieve a saved
2ab60 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 copy of the orig
2ab70 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 inal.** SQL text
2ab80 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 used to create
2ab90 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
2aba0 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 ement] if that s
2abb0 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 tatement was.**
2abc0 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 compiled using e
2abd0 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 ither [sqlite3_p
2abe0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 repare_v2()] or
2abf0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
2ac00 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 16_v2()]..*/.SQL
2ac10 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 ITE_API const ch
2ac20 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 ar *SQLITE_STDCA
2ac30 4c 4c 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 LL sqlite3_sql(s
2ac40 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
2ac50 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 mt);../*.** CAPI
2ac60 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 3REF: Determine
2ac70 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d If An SQL Statem
2ac80 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44 ent Writes The D
2ac90 61 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f atabase.** METHO
2aca0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a D: sqlite3_stmt.
2acb0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
2acc0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 e3_stmt_readonly
2acd0 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 (X) interface re
2ace0 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d turns true (non-
2acf0 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 zero) if.** and
2ad00 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 only if the [pre
2ad10 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2ad20 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 X makes no dire
2ad30 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a ct changes to.**
2ad40 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 the content of
2ad50 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
2ad60 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 e..**.** Note th
2ad70 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d at [application-
2ad80 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
2ad90 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 tions] or.** [vi
2ada0 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 rtual tables] mi
2adb0 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 ght change the d
2adc0 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 atabase indirect
2add0 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66 ly as a side eff
2ade0 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 ect. .** ^(For
2adf0 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 example, if an a
2ae00 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e pplication defin
2ae10 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 es a function "e
2ae20 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 val()" that .**
2ae30 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 calls [sqlite3_e
2ae40 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 xec()], then the
2ae50 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 following SQL s
2ae60 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a tatement would.*
2ae70 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 * change the dat
2ae80 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 abase file throu
2ae90 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a gh side-effects:
2aea0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
2aeb0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 te><pre>.** S
2aec0 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 ELECT eval('DELE
2aed0 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f TE FROM t1') FRO
2aee0 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c M t2;.** </pre><
2aef0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
2af00 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74 ** But because t
2af10 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 he [SELECT] stat
2af20 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 ement does not c
2af30 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 hange the databa
2af40 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 se file.** direc
2af50 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d tly, sqlite3_stm
2af60 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 t_readonly() wou
2af70 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 ld still return
2af80 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 true.)^.**.** ^T
2af90 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 ransaction contr
2afa0 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 ol statements su
2afb0 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b ch as [BEGIN], [
2afc0 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 COMMIT], [ROLLBA
2afd0 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 CK],.** [SAVEPOI
2afe0 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 NT], and [RELEAS
2aff0 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 E] cause sqlite3
2b000 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 _stmt_readonly()
2b010 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c to return true,
2b020 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 .** since the st
2b030 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c atements themsel
2b040 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 ves do not actua
2b050 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 lly modify the d
2b060 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 atabase but.** r
2b070 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 ather they contr
2b080 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 ol the timing of
2b090 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 when other stat
2b0a0 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 ements modify th
2b0b0 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 e .** database.
2b0c0 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 ^The [ATTACH] a
2b0d0 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 nd [DETACH] stat
2b0e0 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 ements also caus
2b0f0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d e.** sqlite3_stm
2b100 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 t_readonly() to
2b110 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 return true sinc
2b120 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 e, while those s
2b130 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 tatements.** cha
2b140 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 nge the configur
2b150 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 ation of a datab
2b160 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 ase connection,
2b170 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 they do not make
2b180 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 .** changes to
2b190 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 the content of t
2b1a0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
2b1b0 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 53 51 s on disk..*/.SQ
2b1c0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
2b1d0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
2b1e0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c te3_stmt_readonl
2b1f0 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a y(sqlite3_stmt *
2b200 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 pStmt);../*.** C
2b210 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 API3REF: Determi
2b220 6e 65 20 49 66 20 41 20 50 72 65 70 61 72 65 64 ne If A Prepared
2b230 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42 Statement Has B
2b240 65 65 6e 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54 een Reset.** MET
2b250 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d HOD: sqlite3_stm
2b260 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c t.**.** ^The sql
2b270 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 ite3_stmt_busy(S
2b280 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
2b290 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 rns true (non-ze
2b2a0 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 ro) if the.** [p
2b2b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2b2c0 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 t] S has been st
2b2d0 65 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f epped at least o
2b2e0 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 nce using .** [s
2b2f0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 qlite3_step(S)]
2b300 62 75 74 20 68 61 73 20 6e 65 69 74 68 65 72 20 but has neither
2b310 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f run to completio
2b320 6e 20 28 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b n (returned.** [
2b330 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 66 72 6f SQLITE_DONE] fro
2b340 6d 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 m [sqlite3_step(
2b350 53 29 5d 29 20 6e 6f 72 0a 2a 2a 20 62 65 65 6e S)]) nor.** been
2b360 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71 reset using [sq
2b370 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e lite3_reset(S)].
2b380 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 ^The sqlite3_s
2b390 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 tmt_busy(S).** i
2b3a0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
2b3b0 20 66 61 6c 73 65 20 69 66 20 53 20 69 73 20 61 false if S is a
2b3c0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 NULL pointer.
2b3d0 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a If S is not a .*
2b3e0 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 * NULL pointer a
2b3f0 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e nd is not a poin
2b400 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b ter to a valid [
2b410 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2b420 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 nt].** object, t
2b430 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 hen the behavior
2b440 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e is undefined an
2b450 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 d probably undes
2b460 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 irable..**.** Th
2b470 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e is interface can
2b480 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 be used in comb
2b490 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 ination [sqlite3
2b4a0 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a _next_stmt()].**
2b4b0 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 to locate all p
2b4c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2b4d0 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 ts associated wi
2b4e0 74 68 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a th a database .*
2b4f0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 * connection tha
2b500 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 t are in need of
2b510 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54 being reset. T
2b520 68 69 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c his can be used,
2b530 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c .** for example,
2b540 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72 in diagnostic r
2b550 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63 outines to searc
2b560 68 20 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a h for prepared .
2b570 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 ** statements th
2b580 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 at are holding a
2b590 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 transaction ope
2b5a0 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 n..*/.SQLITE_API
2b5b0 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
2b5c0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 ALL sqlite3_stmt
2b5d0 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 _busy(sqlite3_st
2b5e0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 mt*);../*.** CAP
2b5f0 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c I3REF: Dynamical
2b600 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f ly Typed Value O
2b610 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 bject.** KEYWORD
2b620 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 S: {protected sq
2b630 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e lite3_value} {un
2b640 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
2b650 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 3_value}.**.** S
2b660 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 QLite uses the s
2b670 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
2b680 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 ect to represent
2b690 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 all values.** t
2b6a0 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 hat can be store
2b6b0 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 d in a database
2b6c0 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 table. SQLite us
2b6d0 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e es dynamic typin
2b6e0 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c g.** for the val
2b6f0 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 ues it stores.
2b700 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 ^Values stored i
2b710 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 n sqlite3_value
2b720 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 objects.** can b
2b730 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 e integers, floa
2b740 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 ting point value
2b750 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 s, strings, BLOB
2b760 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a s, or NULL..**.*
2b770 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c * An sqlite3_val
2b780 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 ue object may be
2b790 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 either "protect
2b7a0 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 ed" or "unprotec
2b7b0 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e ted"..** Some in
2b7c0 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 terfaces require
2b7d0 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c a protected sql
2b7e0 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 ite3_value. Oth
2b7f0 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a er interfaces.**
2b800 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 will accept eit
2b810 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 her a protected
2b820 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 or an unprotecte
2b830 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e d sqlite3_value.
2b840 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 .** Every interf
2b850 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73 ace that accepts
2b860 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 sqlite3_value a
2b870 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 rguments specifi
2b880 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 es.** whether or
2b890 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 not it requires
2b8a0 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c a protected sql
2b8b0 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 54 68 65 ite3_value. The
2b8c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c .** [sqlite3_val
2b8d0 75 65 5f 64 75 70 28 29 5d 20 69 6e 74 65 72 66 ue_dup()] interf
2b8e0 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 ace can be used
2b8f0 74 6f 20 63 6f 6e 73 74 72 75 63 74 20 61 20 6e to construct a n
2b900 65 77 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64 ew .** protected
2b910 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 66 sqlite3_value f
2b920 72 6f 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 rom an unprotect
2b930 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
2b940 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d ..**.** The term
2b950 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e s "protected" an
2b960 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 d "unprotected"
2b970 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 refer to whether
2b980 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 or not.** a mut
2b990 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 ex is held. An
2b9a0 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 internal mutex i
2b9b0 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f s held for a pro
2b9c0 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 tected.** sqlite
2b9d0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 3_value object b
2b9e0 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 ut no mutex is h
2b9f0 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f eld for an unpro
2ba00 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 tected.** sqlite
2ba10 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 3_value object.
2ba20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f If SQLite is co
2ba30 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e mpiled to be sin
2ba40 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 gle-threaded.**
2ba50 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 (with [SQLITE_TH
2ba60 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 READSAFE=0] and
2ba70 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 with [sqlite3_th
2ba80 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 readsafe()] retu
2ba90 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 rning 0).** or i
2baa0 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 f SQLite is run
2bab0 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 in one of reduce
2bac0 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a d mutex modes .*
2bad0 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 * [SQLITE_CONFIG
2bae0 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f _SINGLETHREAD] o
2baf0 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 r [SQLITE_CONFIG
2bb00 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a _MULTITHREAD].**
2bb10 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e then there is n
2bb20 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 o distinction be
2bb30 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 tween protected
2bb40 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a and unprotected.
2bb50 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ** sqlite3_value
2bb60 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 objects and the
2bb70 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e y can be used in
2bb80 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 terchangeably.
2bb90 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 However,.** for
2bba0 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 maximum code por
2bbb0 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 tability it is r
2bbc0 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 ecommended that
2bbd0 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 applications.**
2bbe0 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 still make the d
2bbf0 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 istinction betwe
2bc00 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 en protected and
2bc10 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 unprotected.**
2bc20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
2bc30 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 jects even when
2bc40 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 not strictly req
2bc50 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 uired..**.** ^Th
2bc60 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 e sqlite3_value
2bc70 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 objects that are
2bc80 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d passed as param
2bc90 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a eters into the.*
2bca0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
2bcb0 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e of [application
2bcc0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e -defined SQL fun
2bcd0 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 ctions] are prot
2bce0 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 ected..** ^The s
2bcf0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
2bd00 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a ect returned by.
2bd10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ** [sqlite3_colu
2bd20 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 mn_value()] is u
2bd30 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 nprotected..** U
2bd40 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
2bd50 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 e3_value objects
2bd60 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 may only be use
2bd70 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 d with.** [sqlit
2bd80 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 e3_result_value(
2bd90 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
2bda0 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a bind_value()]..*
2bdb0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 * The [sqlite3_v
2bdc0 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 alue_blob | sqli
2bdd0 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 te3_value_type()
2bde0 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 ] family of.** i
2bdf0 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 nterfaces requir
2be00 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 e protected sqli
2be10 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
2be20 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 s..*/.typedef st
2be30 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 ruct Mem sqlite3
2be40 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 _value;../*.** C
2be50 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e API3REF: SQL Fun
2be60 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 ction Context Ob
2be70 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 ject.**.** The c
2be80 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 ontext in which
2be90 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 an SQL function
2bea0 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 executes is stor
2beb0 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 ed in an.** sqli
2bec0 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 te3_context obje
2bed0 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 ct. ^A pointer
2bee0 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f to an sqlite3_co
2bef0 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 ntext object.**
2bf00 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 is always first
2bf10 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 parameter to [ap
2bf20 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
2bf30 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d d SQL functions]
2bf40 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 ..** The applica
2bf50 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c tion-defined SQL
2bf60 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d function implem
2bf70 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 entation will pa
2bf80 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 ss this.** point
2bf90 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 er through into
2bfa0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 calls to [sqlite
2bfb0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 3_result_int | s
2bfc0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d qlite3_result()]
2bfd0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 ,.** [sqlite3_ag
2bfe0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 gregate_context(
2bff0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 )], [sqlite3_use
2c000 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 r_data()],.** [s
2c010 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 qlite3_context_d
2c020 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 b_handle()], [sq
2c030 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 lite3_get_auxdat
2c040 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 a()],.** and/or
2c050 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 [sqlite3_set_aux
2c060 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 data()]..*/.type
2c070 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
2c080 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 e3_context sqlit
2c090 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a e3_context;../*.
2c0a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e ** CAPI3REF: Bin
2c0b0 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 ding Values To P
2c0c0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e repared Statemen
2c0d0 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 ts.** KEYWORDS:
2c0e0 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d {host parameter}
2c0f0 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 {host parameter
2c100 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 s} {host paramet
2c110 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 er name}.** KEYW
2c120 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d ORDS: {SQL param
2c130 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d eter} {SQL param
2c140 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 eters} {paramete
2c150 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 r binding}.** ME
2c160 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 THOD: sqlite3_st
2c170 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 mt.**.** ^(In th
2c180 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
2c190 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 text input to [s
2c1a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
2c1b0 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 2()] and its var
2c1c0 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 iants,.** litera
2c1d0 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 ls may be replac
2c1e0 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 ed by a [paramet
2c1f0 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 er] that matches
2c200 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e one of followin
2c210 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a g.** templates:.
2c220 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
2c230 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f i> ?.** <li> ?
2c240 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 NNN.** <li> :VV
2c250 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a V.** <li> @VVV.
2c260 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a ** <li> $VVV.**
2c270 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 </ul>.**.** In
2c280 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 the templates ab
2c290 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 ove, NNN represe
2c2a0 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c nts an integer l
2c2b0 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 iteral,.** and V
2c2c0 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e VV represents an
2c2d0 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 alphanumeric id
2c2e0 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 entifier.)^ ^Th
2c2f0 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 e values of thes
2c300 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 e.** parameters
2c310 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f (also called "ho
2c320 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d st parameter nam
2c330 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 es" or "SQL para
2c340 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 meters").** can
2c350 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 be set using the
2c360 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 sqlite3_bind_*(
2c370 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e ) routines defin
2c380 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e ed here..**.** ^
2c390 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
2c3a0 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 nt to the sqlite
2c3b0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 3_bind_*() routi
2c3c0 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a nes is always.**
2c3d0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
2c3e0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d e [sqlite3_stmt]
2c3f0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 object returned
2c400 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 from.** [sqlite
2c410 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
2c420 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e or its variants.
2c430 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f .**.** ^The seco
2c440 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 nd argument is t
2c450 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 he index of the
2c460 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f SQL parameter to
2c470 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 be set..** ^The
2c480 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 leftmost SQL pa
2c490 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 rameter has an i
2c4a0 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 ndex of 1. ^Whe
2c4b0 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 n the same named
2c4c0 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 .** SQL paramete
2c4d0 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 r is used more t
2c4e0 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 han once, second
2c4f0 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a and subsequent.
2c500 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 ** occurrences h
2c510 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 ave the same ind
2c520 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20 ex as the first
2c530 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e occurrence..** ^
2c540 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 The index for na
2c550 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 med parameters c
2c560 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 an be looked up
2c570 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 using the.** [sq
2c580 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
2c590 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 eter_index()] AP
2c5a0 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e I if desired. ^
2c5b0 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 The index.** for
2c5c0 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 "?NNN" paramete
2c5d0 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 rs is the value
2c5e0 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 of NNN..** ^The
2c5f0 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 NNN value must b
2c600 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 e between 1 and
2c610 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d the [sqlite3_lim
2c620 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 it()].** paramet
2c630 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 er [SQLITE_LIMIT
2c640 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 _VARIABLE_NUMBER
2c650 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 ] (default value
2c660 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 : 999)..**.** ^T
2c670 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e he third argumen
2c680 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 t is the value t
2c690 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 o bind to the pa
2c6a0 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 rameter..** ^If
2c6b0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 the third parame
2c6c0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 ter to sqlite3_b
2c6d0 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 ind_text() or sq
2c6e0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 lite3_bind_text1
2c6f0 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 6().** or sqlite
2c700 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 3_bind_blob() is
2c710 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
2c720 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 then the fourth
2c730 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 parameter.** is
2c740 69 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20 ignored and the
2c750 65 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74 68 end result is th
2c760 65 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65 e same as sqlite
2c770 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 3_bind_null()..*
2c780 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 *.** ^(In those
2c790 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 routines that ha
2c7a0 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 ve a fourth argu
2c7b0 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 ment, its value
2c7c0 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 is the.** number
2c7d0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 of bytes in the
2c7e0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 parameter. To
2c7f0 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 be clear: the va
2c800 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 lue is the.** nu
2c810 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 mber of <u>bytes
2c820 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 </u> in the valu
2c830 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 e, not the numbe
2c840 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e r of characters.
2c850 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f )^.** ^If the fo
2c860 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 urth parameter t
2c870 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 o sqlite3_bind_t
2c880 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 ext() or sqlite3
2c890 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a _bind_text16().*
2c8a0 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 * is negative, t
2c8b0 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f hen the length o
2c8c0 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a f the string is.
2c8d0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ** the number of
2c8e0 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 bytes up to the
2c8f0 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d first zero term
2c900 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 inator..** If th
2c910 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
2c920 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 er to sqlite3_bi
2c930 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 nd_blob() is neg
2c940 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 ative, then.** t
2c950 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 he behavior is u
2c960 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 ndefined..** If
2c970 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 a non-negative f
2c980 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
2c990 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 is provided to s
2c9a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
2c9b0 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 ().** or sqlite3
2c9c0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 6f _bind_text16() o
2c9d0 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 r sqlite3_bind_t
2c9e0 65 78 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20 ext64() then.**
2c9f0 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d that parameter m
2ca00 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 ust be the byte
2ca10 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 offset.** where
2ca20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 the NUL terminat
2ca30 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 or would occur a
2ca40 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 ssuming the stri
2ca50 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 ng were NUL.** t
2ca60 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 erminated. If a
2ca70 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 ny NUL character
2ca80 73 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 s occur at byte
2ca90 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 offsets less tha
2caa0 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 n .** the value
2cab0 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 of the fourth pa
2cac0 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 rameter then the
2cad0 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e resulting strin
2cae0 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 g value will.**
2caf0 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 contain embedded
2cb00 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 NULs. The resu
2cb10 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e lt of expression
2cb20 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 s involving stri
2cb30 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 ngs.** with embe
2cb40 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 dded NULs is und
2cb50 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 efined..**.** ^T
2cb60 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e he fifth argumen
2cb70 74 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e t to the BLOB an
2cb80 64 20 73 74 72 69 6e 67 20 62 69 6e 64 69 6e 67 d string binding
2cb90 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 interfaces.** i
2cba0 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 s a destructor u
2cbb0 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f sed to dispose o
2cbc0 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a f the BLOB or.**
2cbd0 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 string after SQ
2cbe0 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 Lite has finishe
2cbf0 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 d with it. ^The
2cc00 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 destructor is c
2cc10 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 alled.** to disp
2cc20 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 ose of the BLOB
2cc30 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 or string even i
2cc40 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 62 69 f the call to bi
2cc50 6e 64 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a nd API fails..**
2cc60 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 ^If the fifth a
2cc70 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 rgument is.** th
2cc80 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 e special value
2cc90 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c [SQLITE_STATIC],
2cca0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 then SQLite ass
2ccb0 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a umes that the.**
2ccc0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 information is
2ccd0 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e in static, unman
2cce0 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 aged space and d
2ccf0 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 oes not need to
2cd00 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 be freed..** ^If
2cd10 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d the fifth argum
2cd20 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 ent has the valu
2cd30 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 e [SQLITE_TRANSI
2cd40 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 ENT], then.** SQ
2cd50 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f Lite makes its o
2cd60 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 wn private copy
2cd70 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 of the data imme
2cd80 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a diately, before.
2cd90 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 ** the sqlite3_b
2cda0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 ind_*() routine
2cdb0 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e returns..**.** ^
2cdc0 54 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 The sixth argume
2cdd0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 nt to sqlite3_bi
2cde0 6e 64 5f 74 65 78 74 36 34 28 29 20 6d 75 73 74 nd_text64() must
2cdf0 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 be one of.** [S
2ce00 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 QLITE_UTF8], [SQ
2ce10 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 LITE_UTF16], [SQ
2ce20 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f LITE_UTF16BE], o
2ce30 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c r [SQLITE_UTF16L
2ce40 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66 79 E].** to specify
2ce50 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 the encoding of
2ce60 20 74 68 65 20 74 65 78 74 20 69 6e 20 74 68 65 the text in the
2ce70 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
2ce80 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 73 69 78 . If.** the six
2ce90 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 th argument to s
2cea0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
2ceb0 36 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 64() is not one
2cec0 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 of the.** allowe
2ced0 64 20 76 61 6c 75 65 73 20 73 68 6f 77 6e 20 61 d values shown a
2cee0 62 6f 76 65 2c 20 6f 72 20 69 66 20 74 68 65 20 bove, or if the
2cef0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 text encoding is
2cf00 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72 different.** fr
2cf10 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 om the encoding
2cf20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 specified by the
2cf30 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 sixth parameter
2cf40 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 , then the behav
2cf50 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 ior.** is undefi
2cf60 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ned..**.** ^The
2cf70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 sqlite3_bind_zer
2cf80 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 oblob() routine
2cf90 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 binds a BLOB of
2cfa0 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a length N that.**
2cfb0 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 is filled with
2cfc0 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f zeroes. ^A zero
2cfd0 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 blob uses a fixe
2cfe0 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f d amount of memo
2cff0 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 ry.** (just an i
2d000 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 nteger to hold i
2d010 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 ts size) while i
2d020 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 t is being proce
2d030 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f ssed..** Zeroblo
2d040 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 bs are intended
2d050 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 to serve as plac
2d060 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f eholders for BLO
2d070 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 Bs whose.** cont
2d080 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 ent is later wri
2d090 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 tten using.** [s
2d0a0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e qlite3_blob_open
2d0b0 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 | incremental B
2d0c0 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 LOB I/O] routine
2d0d0 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 s..** ^A negativ
2d0e0 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 e value for the
2d0f0 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 zeroblob results
2d100 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 in a zero-lengt
2d110 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 h BLOB..**.** ^I
2d120 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c f any of the sql
2d130 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f ite3_bind_*() ro
2d140 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 utines are calle
2d150 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f d with a NULL po
2d160 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 inter.** for the
2d170 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2d180 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 ment] or with a
2d190 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2d1a0 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 nt for which.**
2d1b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
2d1c0 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 has been called
2d1d0 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 more recently t
2d1e0 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 han [sqlite3_res
2d1f0 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 et()],.** then t
2d200 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 he call will ret
2d210 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 urn [SQLITE_MISU
2d220 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c SE]. If any sql
2d230 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 ite3_bind_().**
2d240 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 routine is passe
2d250 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 d a [prepared st
2d260 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 atement] that ha
2d270 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 s been finalized
2d280 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 , the.** result
2d290 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 is undefined and
2d2a0 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 probably harmfu
2d2b0 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e l..**.** ^Bindin
2d2c0 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 gs are not clear
2d2d0 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 ed by the [sqlit
2d2e0 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 e3_reset()] rout
2d2f0 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 ine..** ^Unbound
2d300 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 parameters are
2d310 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e interpreted as N
2d320 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ULL..**.** ^The
2d330 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 sqlite3_bind_* r
2d340 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b outines return [
2d350 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 SQLITE_OK] on su
2d360 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b ccess or an.** [
2d370 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 error code] if a
2d380 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f nything goes wro
2d390 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f ng..** ^[SQLITE_
2d3a0 54 4f 4f 42 49 47 5d 20 6d 69 67 68 74 20 62 65 TOOBIG] might be
2d3b0 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 returned if the
2d3c0 20 73 69 7a 65 20 6f 66 20 61 20 73 74 72 69 6e size of a strin
2d3d0 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 g or BLOB.** exc
2d3e0 65 65 64 73 20 6c 69 6d 69 74 73 20 69 6d 70 6f eeds limits impo
2d3f0 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f sed by [sqlite3_
2d400 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c limit]([SQLITE_L
2d410 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 IMIT_LENGTH]) or
2d420 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f .** [SQLITE_MAX_
2d430 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 LENGTH]..** ^[SQ
2d440 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 LITE_RANGE] is r
2d450 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 eturned if the p
2d460 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 arameter.** inde
2d470 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 x is out of rang
2d480 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d e. ^[SQLITE_NOM
2d490 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 EM] is returned
2d4a0 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c if malloc() fail
2d4b0 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 s..**.** See als
2d4c0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 o: [sqlite3_bind
2d4d0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 _parameter_count
2d4e0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
2d4f0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
2d500 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 name()], and [sq
2d510 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
2d520 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a eter_index()]..*
2d530 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
2d540 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
2d550 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
2d560 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c b(sqlite3_stmt*,
2d570 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 int, const void
2d580 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a *, int n, void(*
2d590 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 )(void*));.SQLIT
2d5a0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
2d5b0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
2d5c0 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73 71 6c _bind_blob64(sql
2d5d0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c ite3_stmt*, int,
2d5e0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 73 71 const void*, sq
2d5f0 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 lite3_uint64,.
2d600 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2d610 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f void(*)(vo
2d620 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 id*));.SQLITE_AP
2d630 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
2d640 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e CALL sqlite3_bin
2d650 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 d_double(sqlite3
2d660 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 _stmt*, int, dou
2d670 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ble);.SQLITE_API
2d680 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
2d690 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 ALL sqlite3_bind
2d6a0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d _int(sqlite3_stm
2d6b0 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 53 t*, int, int);.S
2d6c0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 QLITE_API int SQ
2d6d0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
2d6e0 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 ite3_bind_int64(
2d6f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
2d700 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 nt, sqlite3_int6
2d710 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 4);.SQLITE_API i
2d720 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c nt SQLITE_STDCAL
2d730 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e L sqlite3_bind_n
2d740 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ull(sqlite3_stmt
2d750 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f *, int);.SQLITE_
2d760 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 API int SQLITE_S
2d770 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 TDCALL sqlite3_b
2d780 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 ind_text(sqlite3
2d790 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 _stmt*,int,const
2d7a0 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 char*,int,void(
2d7b0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 *)(void*));.SQLI
2d7c0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
2d7d0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
2d7e0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 3_bind_text16(sq
2d7f0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
2d800 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 , const void*, i
2d810 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 nt, void(*)(void
2d820 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 *));.SQLITE_API
2d830 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 int SQLITE_STDCA
2d840 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f LL sqlite3_bind_
2d850 74 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f 73 text64(sqlite3_s
2d860 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 tmt*, int, const
2d870 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f char*, sqlite3_
2d880 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 uint64,.
2d890 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2d8a0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c void(*)(void*),
2d8b0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65 unsigned char e
2d8c0 6e 63 6f 64 69 6e 67 29 3b 0a 53 51 4c 49 54 45 ncoding);.SQLITE
2d8d0 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f _API int SQLITE_
2d8e0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
2d8f0 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 bind_value(sqlit
2d900 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 e3_stmt*, int, c
2d910 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c onst sqlite3_val
2d920 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ue*);.SQLITE_API
2d930 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
2d940 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 ALL sqlite3_bind
2d950 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 _zeroblob(sqlite
2d960 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 3_stmt*, int, in
2d970 74 20 6e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 t n);.SQLITE_API
2d980 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
2d990 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 ALL sqlite3_bind
2d9a0 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73 71 6c 69 _zeroblob64(sqli
2d9b0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
2d9c0 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b sqlite3_uint64);
2d9d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2d9e0 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 : Number Of SQL
2d9f0 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 4d 45 Parameters.** ME
2da00 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 THOD: sqlite3_st
2da10 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 mt.**.** ^This r
2da20 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 outine can be us
2da30 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e ed to find the n
2da40 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 umber of [SQL pa
2da50 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 rameters].** in
2da60 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
2da70 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 ement]. SQL par
2da80 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 ameters are toke
2da90 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 ns of the.** for
2daa0 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 m "?", "?NNN", "
2dab0 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f :AAA", "$AAA", o
2dac0 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65 r "@AAA" that se
2dad0 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 rve as.** placeh
2dae0 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 olders for value
2daf0 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 s that are [sqli
2db00 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 te3_bind_blob |
2db10 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 bound].** to the
2db20 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 parameters at a
2db30 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a later time..**.
2db40 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e ** ^(This routin
2db50 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 e actually retur
2db60 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 ns the index of
2db70 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 the largest (rig
2db80 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d htmost).** param
2db90 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f eter. For all fo
2dba0 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c rms except ?NNN,
2dbb0 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 this will corre
2dbc0 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 spond to the.**
2dbd0 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 number of unique
2dbe0 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 parameters. If
2dbf0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 parameters of t
2dc00 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 he ?NNN form are
2dc10 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 used,.** there
2dc20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 may be gaps in t
2dc30 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a he list.)^.**.**
2dc40 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 See also: [sqli
2dc50 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 te3_bind_blob|sq
2dc60 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a lite3_bind()],.*
2dc70 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
2dc80 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 parameter_name()
2dc90 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 ], and.** [sqlit
2dca0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
2dcb0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 r_index()]..*/.S
2dcc0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 QLITE_API int SQ
2dcd0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
2dce0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
2dcf0 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 ter_count(sqlite
2dd00 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 3_stmt*);../*.**
2dd10 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 CAPI3REF: Name
2dd20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 Of A Host Parame
2dd30 74 65 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 ter.** METHOD: s
2dd40 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a qlite3_stmt.**.*
2dd50 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 * ^The sqlite3_b
2dd60 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 ind_parameter_na
2dd70 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 me(P,N) interfac
2dd80 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 e returns.** the
2dd90 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 name of the N-t
2dda0 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 h [SQL parameter
2ddb0 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 ] in the [prepar
2ddc0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e ed statement] P.
2ddd0 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 .** ^(SQL parame
2dde0 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d ters of the form
2ddf0 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 "?NNN" or ":AAA
2de00 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 " or "@AAA" or "
2de10 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 $AAA".** have a
2de20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 name which is th
2de30 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 e string "?NNN"
2de40 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 or ":AAA" or "@A
2de50 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a AA" or "$AAA".**
2de60 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a respectively..*
2de70 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 * In other words
2de80 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a , the initial ":
2de90 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 " or "$" or "@"
2dea0 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 or "?".** is inc
2deb0 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 luded as part of
2dec0 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 the name.)^.**
2ded0 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 ^Parameters of t
2dee0 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 he form "?" with
2def0 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 out a following
2df00 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 integer have no
2df10 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 name.** and are
2df20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 referred to as "
2df30 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e nameless" or "an
2df40 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 onymous paramete
2df50 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 rs"..**.** ^The
2df60 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d first host param
2df70 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 eter has an inde
2df80 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a x of 1, not 0..*
2df90 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c *.** ^If the val
2dfa0 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 ue N is out of r
2dfb0 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e ange or if the N
2dfc0 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 -th parameter is
2dfd0 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 .** nameless, th
2dfe0 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 en NULL is retur
2dff0 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 ned. ^The retur
2e000 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a ned string is.**
2e010 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 always in UTF-8
2e020 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 encoding even i
2e030 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 f the named para
2e040 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 meter was.** ori
2e050 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 ginally specifie
2e060 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b d as UTF-16 in [
2e070 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
2e080 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 6()] or.** [sqli
2e090 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
2e0a0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ()]..**.** See a
2e0b0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 lso: [sqlite3_bi
2e0c0 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f nd_blob|sqlite3_
2e0d0 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c bind()],.** [sql
2e0e0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
2e0f0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e ter_count()], an
2e100 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 d.** [sqlite3_bi
2e110 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 nd_parameter_ind
2e120 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 ex()]..*/.SQLITE
2e130 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 _API const char
2e140 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 *SQLITE_STDCALL
2e150 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
2e160 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 ameter_name(sqli
2e170 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b te3_stmt*, int);
2e180 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2e190 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 : Index Of A Par
2e1a0 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69 ameter With A Gi
2e1b0 76 65 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 ven Name.** METH
2e1c0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 OD: sqlite3_stmt
2e1d0 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 .**.** ^Return t
2e1e0 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 he index of an S
2e1f0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 QL parameter giv
2e200 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 en its name. ^T
2e210 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 he.** index valu
2e220 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 e returned is su
2e230 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 itable for use a
2e240 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 s the second.**
2e250 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 parameter to [sq
2e260 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c lite3_bind_blob|
2e270 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e sqlite3_bind()].
2e280 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 ^A zero.** is
2e290 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d returned if no m
2e2a0 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 atching paramete
2e2b0 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 r is found. ^Th
2e2c0 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e e parameter.** n
2e2d0 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 ame must be give
2e2e0 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 n in UTF-8 even
2e2f0 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 if the original
2e300 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 statement.** was
2e310 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 prepared from U
2e320 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 TF-16 text using
2e330 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2e340 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a e16_v2()]..**.**
2e350 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 See also: [sqli
2e360 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 te3_bind_blob|sq
2e370 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a lite3_bind()],.*
2e380 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
2e390 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 parameter_count(
2e3a0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 )], and.** [sqli
2e3b0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
2e3c0 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a er_index()]..*/.
2e3d0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
2e3e0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
2e3f0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
2e400 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 eter_index(sqlit
2e410 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 e3_stmt*, const
2e420 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f char *zName);../
2e430 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
2e440 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 eset All Binding
2e450 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 s On A Prepared
2e460 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 Statement.** MET
2e470 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d HOD: sqlite3_stm
2e480 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 t.**.** ^Contrar
2e490 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 y to the intuiti
2e4a0 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c on of many, [sql
2e4b0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f ite3_reset()] do
2e4c0 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 es not reset.**
2e4d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e the [sqlite3_bin
2e4e0 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 d_blob | binding
2e4f0 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 s] on a [prepare
2e500 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a d statement]..**
2e510 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 ^Use this routi
2e520 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 ne to reset all
2e530 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 host parameters
2e540 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 to NULL..*/.SQLI
2e550 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
2e560 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
2e570 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 3_clear_bindings
2e580 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b (sqlite3_stmt*);
2e590 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2e5a0 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 : Number Of Colu
2e5b0 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 mns In A Result
2e5c0 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 Set.** METHOD: s
2e5d0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a qlite3_stmt.**.*
2e5e0 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 * ^Return the nu
2e5f0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 mber of columns
2e600 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 in the result se
2e610 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 t returned by th
2e620 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 e.** [prepared s
2e630 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 tatement]. ^This
2e640 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
2e650 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 0 if pStmt is a
2e660 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 n SQL.** stateme
2e670 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 nt that does not
2e680 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f return data (fo
2e690 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 r example an [UP
2e6a0 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 DATE])..**.** Se
2e6b0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 e also: [sqlite3
2e6c0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a _data_count()].*
2e6d0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
2e6e0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
2e6f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 sqlite3_column_c
2e700 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d ount(sqlite3_stm
2e710 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a t *pStmt);../*.*
2e720 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 * CAPI3REF: Colu
2e730 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 mn Names In A Re
2e740 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 sult Set.** METH
2e750 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 OD: sqlite3_stmt
2e760 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f .**.** ^These ro
2e770 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 utines return th
2e780 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 e name assigned
2e790 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 to a particular
2e7a0 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 column.** in the
2e7b0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 result set of a
2e7c0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d [SELECT] statem
2e7d0 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 ent. ^The sqlit
2e7e0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 e3_column_name()
2e7f0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 .** interface re
2e800 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
2e810 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e to a zero-termin
2e820 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e ated UTF-8 strin
2e830 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 g.** and sqlite3
2e840 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 _column_name16()
2e850 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
2e860 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 er to a zero-ter
2e870 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 minated.** UTF-1
2e880 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 6 string. ^The
2e890 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
2e8a0 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 is the [prepared
2e8b0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 statement].** t
2e8c0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 hat implements t
2e8d0 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 he [SELECT] stat
2e8e0 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f ement. ^The seco
2e8f0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 nd parameter is
2e900 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 the.** column nu
2e910 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 mber. ^The left
2e920 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e most column is n
2e930 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e umber 0..**.** ^
2e940 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 The returned str
2e950 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 ing pointer is v
2e960 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 alid until eithe
2e970 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 r the [prepared
2e980 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 statement].** is
2e990 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 destroyed by [s
2e9a0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
2e9b0 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 )] or until the
2e9c0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 statement is aut
2e9d0 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 omatically.** re
2e9e0 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 prepared by the
2e9f0 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 first call to [s
2ea00 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 qlite3_step()] f
2ea10 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 or a particular
2ea20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 run.** or until
2ea30 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f the next call to
2ea40 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 .** sqlite3_colu
2ea50 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c mn_name() or sql
2ea60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 ite3_column_name
2ea70 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 16() on the same
2ea80 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e column..**.** ^
2ea90 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f If sqlite3_mallo
2eaa0 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 c() fails during
2eab0 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 the processing
2eac0 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e of either routin
2ead0 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c e.** (for exampl
2eae0 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 e during a conve
2eaf0 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 rsion from UTF-8
2eb00 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e to UTF-16) then
2eb10 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 a.** NULL point
2eb20 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a er is returned..
2eb30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 **.** ^The name
2eb40 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 of a result colu
2eb50 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 mn is the value
2eb60 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 of the "AS" clau
2eb70 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 se for.** that c
2eb80 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 olumn, if there
2eb90 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e is an AS clause.
2eba0 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f If there is no
2ebb0 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 AS clause.** th
2ebc0 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 en the name of t
2ebd0 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 he column is uns
2ebe0 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 pecified and may
2ebf0 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 change from.**
2ec00 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 one release of S
2ec10 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 QLite to the nex
2ec20 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 t..*/.SQLITE_API
2ec30 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c const char *SQL
2ec40 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
2ec50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 te3_column_name(
2ec60 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
2ec70 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 nt N);.SQLITE_AP
2ec80 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 I const void *SQ
2ec90 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
2eca0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 ite3_column_name
2ecb0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
2ecc0 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a , int N);../*.**
2ecd0 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 CAPI3REF: Sourc
2ece0 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 e Of Data In A Q
2ecf0 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d uery Result.** M
2ed00 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 ETHOD: sqlite3_s
2ed10 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 tmt.**.** ^These
2ed20 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 routines provid
2ed30 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 e a means to det
2ed40 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 ermine the datab
2ed50 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a ase, table, and.
2ed60 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 ** table column
2ed70 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 that is the orig
2ed80 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c in of a particul
2ed90 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e ar result column
2eda0 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 in.** [SELECT]
2edb0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 statement..** ^T
2edc0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 he name of the d
2edd0 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 atabase or table
2ede0 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 or column can b
2edf0 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a e returned as.**
2ee00 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 either a UTF-8
2ee10 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 or UTF-16 string
2ee20 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 . ^The _databas
2ee30 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 e_ routines retu
2ee40 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 rn.** the databa
2ee50 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 se name, the _ta
2ee60 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 ble_ routines re
2ee70 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e turn the table n
2ee80 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 ame, and.** the
2ee90 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 origin_ routines
2eea0 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 return the colu
2eeb0 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 mn name..** ^The
2eec0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 returned string
2eed0 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 is valid until
2eee0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
2eef0 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 atement] is dest
2ef00 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b royed.** using [
2ef10 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
2ef20 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 ()] or until the
2ef30 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 statement is au
2ef40 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 tomatically.** r
2ef50 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 eprepared by the
2ef60 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b first call to [
2ef70 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
2ef80 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 for a particular
2ef90 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c run.** or until
2efa0 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d the same inform
2efb0 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 ation is request
2efc0 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 ed.** again in a
2efd0 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 different encod
2efe0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ing..**.** ^The
2eff0 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 names returned a
2f000 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 re the original
2f010 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 un-aliased names
2f020 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 of the.** datab
2f030 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 ase, table, and
2f040 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 column..**.** ^T
2f050 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
2f060 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 t to these inter
2f070 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 faces is a [prep
2f080 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e ared statement].
2f090 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 .** ^These funct
2f0a0 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f ions return info
2f0b0 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 rmation about th
2f0c0 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c e Nth result col
2f0d0 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a umn returned by.
2f0e0 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 ** the statement
2f0f0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 , where N is the
2f100 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e second function
2f110 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 argument..** ^T
2f120 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c he left-most col
2f130 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 umn is column 0
2f140 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e for these routin
2f150 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 es..**.** ^If th
2f160 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 e Nth column ret
2f170 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 urned by the sta
2f180 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 tement is an exp
2f190 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 ression or.** su
2f1a0 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f bquery and is no
2f1b0 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 t a column value
2f1c0 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 , then all of th
2f1d0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 ese functions re
2f1e0 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e turn.** NULL. ^
2f1f0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 These routine mi
2f200 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 ght also return
2f210 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 NULL if a memory
2f220 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f allocation erro
2f230 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f r.** occurs. ^O
2f240 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 therwise, they r
2f250 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f eturn the name o
2f260 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64 f the attached d
2f270 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a atabase, table,.
2f280 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 ** or column tha
2f290 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 t query result c
2f2a0 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 olumn was extrac
2f2b0 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 ted from..**.**
2f2c0 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 ^As with all oth
2f2d0 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 er SQLite APIs,
2f2e0 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 those whose name
2f2f0 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 s end with "16"
2f300 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 return.** UTF-16
2f310 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 encoded strings
2f320 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 and the other f
2f330 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 unctions return
2f340 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 UTF-8..**.** ^Th
2f350 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c ese APIs are onl
2f360 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 y available if t
2f370 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 he library was c
2f380 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 ompiled with the
2f390 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 .** [SQLITE_ENAB
2f3a0 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 LE_COLUMN_METADA
2f3b0 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 TA] C-preprocess
2f3c0 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a or symbol..**.**
2f3d0 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 If two or more
2f3e0 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 threads call one
2f3f0 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 or more of thes
2f400 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e e routines again
2f410 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 st the same.** p
2f420 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2f430 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 t and column at
2f440 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 the same time th
2f450 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 en the results a
2f460 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e re.** undefined.
2f470 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 .**.** If two or
2f480 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 more threads ca
2f490 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a ll one or more.*
2f4a0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d * [sqlite3_colum
2f4b0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 n_database_name
2f4c0 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 | column metadat
2f4d0 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a a interfaces].**
2f4e0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 for the same [p
2f4f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2f500 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f t] and result co
2f510 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 lumn.** at the s
2f520 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 ame time then th
2f530 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e e results are un
2f540 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 defined..*/.SQLI
2f550 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 TE_API const cha
2f560 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c r *SQLITE_STDCAL
2f570 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e L sqlite3_column
2f580 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 _database_name(s
2f590 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 qlite3_stmt*,int
2f5a0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f );.SQLITE_API co
2f5b0 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 nst void *SQLITE
2f5c0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
2f5d0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 _column_database
2f5e0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f _name16(sqlite3_
2f5f0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 stmt*,int);.SQLI
2f600 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 TE_API const cha
2f610 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c r *SQLITE_STDCAL
2f620 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e L sqlite3_column
2f630 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 _table_name(sqli
2f640 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a te3_stmt*,int);.
2f650 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
2f660 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 void *SQLITE_ST
2f670 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f DCALL sqlite3_co
2f680 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 lumn_table_name1
2f690 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
2f6a0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 int);.SQLITE_API
2f6b0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c const char *SQL
2f6c0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
2f6d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 te3_column_origi
2f6e0 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 n_name(sqlite3_s
2f6f0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 tmt*,int);.SQLIT
2f700 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 E_API const void
2f710 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c *SQLITE_STDCALL
2f720 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2f730 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 origin_name16(sq
2f740 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
2f750 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2f760 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 F: Declared Data
2f770 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 type Of A Query
2f780 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 Result.** METHOD
2f790 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a : sqlite3_stmt.*
2f7a0 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74 *.** ^(The first
2f7b0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 parameter is a
2f7c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2f7d0 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 ent]..** If this
2f7e0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 statement is a
2f7f0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 [SELECT] stateme
2f800 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 nt and the Nth c
2f810 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 olumn of the.**
2f820 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 returned result
2f830 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c set of that [SEL
2f840 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 ECT] is a table
2f850 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a column (not an.*
2f860 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 * expression or
2f870 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 subquery) then t
2f880 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 he declared type
2f890 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a of the table.**
2f8a0 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 column is retur
2f8b0 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 ned.)^ ^If the
2f8c0 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 Nth column of th
2f8d0 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 e result set is
2f8e0 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e an.** expression
2f8f0 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 or subquery, th
2f900 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 en a NULL pointe
2f910 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a r is returned..*
2f920 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 * ^The returned
2f930 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 string is always
2f940 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a UTF-8 encoded..
2f950 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d **.** ^(For exam
2f960 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 ple, given the d
2f970 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a atabase schema:.
2f980 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 **.** CREATE TAB
2f990 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 LE t1(c1 VARIANT
2f9a0 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 );.**.** and the
2f9b0 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 following state
2f9c0 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 ment to be compi
2f9d0 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 led:.**.** SELEC
2f9e0 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f T c1 + 1, c1 FRO
2f9f0 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 M t1;.**.** this
2fa00 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 routine would r
2fa10 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 eturn the string
2fa20 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 "VARIANT" for t
2fa30 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 he second result
2fa40 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 .** column (i==1
2fa50 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f ), and a NULL po
2fa60 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 inter for the fi
2fa70 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d rst result colum
2fa80 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a n (i==0).)^.**.*
2fa90 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64 * ^SQLite uses d
2faa0 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 ynamic run-time
2fab0 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 typing. ^So jus
2fac0 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 t because a colu
2fad0 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 mn.** is declare
2fae0 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 d to contain a p
2faf0 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 articular type d
2fb00 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 oes not mean tha
2fb10 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 t the.** data st
2fb20 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c ored in that col
2fb30 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 umn is of the de
2fb40 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 clared type. SQ
2fb50 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e Lite is.** stron
2fb60 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 gly typed, but t
2fb70 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e he typing is dyn
2fb80 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e amic not static.
2fb90 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 ^Type.** is as
2fba0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e sociated with in
2fbb0 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c dividual values,
2fbc0 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f not with the co
2fbd0 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 ntainers.** used
2fbe0 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 to hold those v
2fbf0 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 alues..*/.SQLITE
2fc00 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 _API const char
2fc10 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 *SQLITE_STDCALL
2fc20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 sqlite3_column_d
2fc30 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f ecltype(sqlite3_
2fc40 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 stmt*,int);.SQLI
2fc50 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 TE_API const voi
2fc60 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c d *SQLITE_STDCAL
2fc70 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e L sqlite3_column
2fc80 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 _decltype16(sqli
2fc90 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a te3_stmt*,int);.
2fca0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2fcb0 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c Evaluate An SQL
2fcc0 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 Statement.** ME
2fcd0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 THOD: sqlite3_st
2fce0 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 mt.**.** After a
2fcf0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2fd00 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 ment] has been p
2fd10 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 repared using ei
2fd20 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ther.** [sqlite3
2fd30 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f _prepare_v2()] o
2fd40 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 r [sqlite3_prepa
2fd50 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e re16_v2()] or on
2fd60 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a e of the legacy.
2fd70 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 ** interfaces [s
2fd80 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 qlite3_prepare()
2fd90 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 ] or [sqlite3_pr
2fda0 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 epare16()], this
2fdb0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 function.** mus
2fdc0 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 t be called one
2fdd0 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f or more times to
2fde0 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 evaluate the st
2fdf0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 atement..**.** T
2fe00 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 he details of th
2fe10 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 e behavior of th
2fe20 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 e sqlite3_step()
2fe30 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e interface depen
2fe40 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 d.** on whether
2fe50 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 the statement wa
2fe60 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 s prepared using
2fe70 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 the newer "v2"
2fe80 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 interface.** [sq
2fe90 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
2fea0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
2feb0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
2fec0 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 or the older le
2fed0 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 gacy.** interfac
2fee0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 e [sqlite3_prepa
2fef0 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 re()] and [sqlit
2ff00 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e e3_prepare16()].
2ff10 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 The use of the
2ff20 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 .** new "v2" int
2ff30 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d erface is recomm
2ff40 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 ended for new ap
2ff50 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 plications but t
2ff60 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 he legacy.** int
2ff70 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 erface will cont
2ff80 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f inue to be suppo
2ff90 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 rted..**.** ^In
2ffa0 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 the legacy inter
2ffb0 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e face, the return
2ffc0 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 value will be e
2ffd0 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 ither [SQLITE_BU
2ffe0 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f SY],.** [SQLITE_
2fff0 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 DONE], [SQLITE_R
30000 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 OW], [SQLITE_ERR
30010 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f OR], or [SQLITE_
30020 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 MISUSE]..** ^Wit
30030 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 h the "v2" inter
30040 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 face, any of the
30050 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 other [result c
30060 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 odes] or.** [ext
30070 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
30080 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 es] might be ret
30090 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a urned as well..*
300a0 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 *.** ^[SQLITE_BU
300b0 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 SY] means that t
300c0 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 he database engi
300d0 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f ne was unable to
300e0 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 acquire the.**
300f0 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 database locks i
30100 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 t needs to do it
30110 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 s job. ^If the
30120 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b statement is a [
30130 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 COMMIT].** or oc
30140 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 curs outside of
30150 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e an explicit tran
30160 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f saction, then yo
30170 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a u can retry the.
30180 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 ** statement. I
30190 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 f the statement
301a0 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 is not a [COMMIT
301b0 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 ] and occurs wit
301c0 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 hin an.** explic
301d0 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 it transaction t
301e0 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 hen you should r
301f0 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e ollback the tran
30200 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a saction before.*
30210 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a * continuing..**
30220 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e .** ^[SQLITE_DON
30230 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 E] means that th
30240 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 e statement has
30250 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 finished executi
30260 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c ng.** successful
30270 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 ly. sqlite3_ste
30280 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 p() should not b
30290 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f e called again o
302a0 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a n this virtual.*
302b0 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 * machine withou
302c0 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 t first calling
302d0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
302e0 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 ] to reset the v
302f0 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e irtual.** machin
30300 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e e back to its in
30310 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a itial state..**.
30320 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 ** ^If the SQL s
30330 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 tatement being e
30340 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 xecuted returns
30350 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b any data, then [
30360 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 SQLITE_ROW].** i
30370 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 s returned each
30380 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f time a new row o
30390 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 f data is ready
303a0 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 for processing b
303b0 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e y the.** caller.
303c0 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 The values may
303d0 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e be accessed usin
303e0 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 g the [column ac
303f0 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e cess functions].
30400 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 .** sqlite3_step
30410 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 () is called aga
30420 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 in to retrieve t
30430 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 he next row of d
30440 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c ata..**.** ^[SQL
30450 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 ITE_ERROR] means
30460 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 that a run-time
30470 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 error (such as
30480 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 a constraint.**
30490 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f violation) has o
304a0 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 ccurred. sqlite
304b0 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 3_step() should
304c0 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 not be called ag
304d0 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d ain on.** the VM
304e0 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 . More informati
304f0 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 on may be found
30500 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 by calling [sqli
30510 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a te3_errmsg()]..*
30520 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 * ^With the lega
30530 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 cy interface, a
30540 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 more specific er
30550 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 ror code (for ex
30560 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 ample,.** [SQLIT
30570 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 E_INTERRUPT], [S
30580 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b QLITE_SCHEMA], [
30590 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c SQLITE_CORRUPT],
305a0 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a and so forth).*
305b0 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 * can be obtaine
305c0 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 d by calling [sq
305d0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f lite3_reset()] o
305e0 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 n the.** [prepar
305f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 ed statement].
30600 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 ^In the "v2" int
30610 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d erface,.** the m
30620 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 ore specific err
30630 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 or code is retur
30640 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 ned directly by
30650 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a sqlite3_step()..
30660 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 **.** [SQLITE_MI
30670 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 SUSE] means that
30680 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e the this routin
30690 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 e was called ina
306a0 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a ppropriately..**
306b0 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20 Perhaps it was
306c0 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 called on a [pre
306d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
306e0 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 that has.** alr
306f0 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 eady been [sqlit
30700 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 e3_finalize | fi
30710 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f nalized] or on o
30720 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 ne that had.** p
30730 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e reviously return
30740 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 ed [SQLITE_ERROR
30750 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e ] or [SQLITE_DON
30760 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 E]. Or it could
30770 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 .** be the case
30780 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 that the same da
30790 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
307a0 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 n is being used
307b0 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 by two or.** mor
307c0 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 e threads at the
307d0 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 same moment in
307e0 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 time..**.** For
307f0 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 all versions of
30800 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 SQLite up to and
30810 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 including 3.6.2
30820 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 3.1, a call to.*
30830 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 * [sqlite3_reset
30840 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 ()] was required
30850 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 after sqlite3_s
30860 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 tep() returned a
30870 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 nything.** other
30880 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f than [SQLITE_RO
30890 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 W] before any su
308a0 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 bsequent invocat
308b0 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 ion of.** sqlite
308c0 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 3_step(). Failu
308d0 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 re to reset the
308e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
308f0 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 nt using .** [sq
30900 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 lite3_reset()] w
30910 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 ould result in a
30920 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 n [SQLITE_MISUSE
30930 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a ] return from.**
30940 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e sqlite3_step().
30950 20 20 42 75 74 20 61 66 74 65 72 20 76 65 72 73 But after vers
30960 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 ion 3.6.23.1, sq
30970 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 lite3_step() beg
30980 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 an.** calling [s
30990 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
309a0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e automatically in
309b0 20 74 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e this circumstan
309c0 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 ce rather.** tha
309d0 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c n returning [SQL
309e0 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 ITE_MISUSE]. Th
309f0 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 is is not consid
30a00 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 ered a compatibi
30a10 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 lity.** break be
30a20 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 cause any applic
30a30 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 ation that ever
30a40 72 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 receives an SQLI
30a50 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a TE_MISUSE error.
30a60 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 ** is broken by
30a70 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 definition. The
30a80 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 [SQLITE_OMIT_AU
30a90 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 TORESET] compile
30aa0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 -time option.**
30ab0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 can be used to r
30ac0 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 estore the legac
30ad0 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a y behavior..**.*
30ae0 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 * <b>Goofy Inter
30af0 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 face Alert:</b>
30b00 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e In the legacy in
30b10 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c terface, the sql
30b20 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 ite3_step().** A
30b30 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e PI always return
30b40 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f s a generic erro
30b50 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f r code, [SQLITE_
30b60 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e ERROR], followin
30b70 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f g any.** error o
30b80 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 ther than [SQLIT
30b90 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c E_BUSY] and [SQL
30ba0 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f ITE_MISUSE]. Yo
30bb0 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b u must call.** [
30bc0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
30bd0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e or [sqlite3_fin
30be0 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 alize()] in orde
30bf0 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 r to find one of
30c00 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 the.** specific
30c10 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 [error codes] t
30c20 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72 hat better descr
30c30 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a ibes the error..
30c40 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 ** We admit that
30c50 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 this is a goofy
30c60 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 design. The pr
30c70 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 oblem has been f
30c80 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 ixed.** with the
30c90 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e "v2" interface.
30ca0 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 If you prepare
30cb0 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c all of your SQL
30cc0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 statements.** u
30cd0 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c sing either [sql
30ce0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
30cf0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 )] or [sqlite3_p
30d00 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 repare16_v2()] i
30d10 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 nstead.** of the
30d20 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 legacy [sqlite3
30d30 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 _prepare()] and
30d40 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
30d50 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 16()] interfaces
30d60 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f ,.** then the mo
30d70 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 re specific [err
30d80 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 or codes] are re
30d90 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a turned directly.
30da0 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 ** by sqlite3_st
30db0 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f ep(). The use o
30dc0 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 f the "v2" inter
30dd0 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e face is recommen
30de0 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ded..*/.SQLITE_A
30df0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 PI int SQLITE_ST
30e00 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 74 DCALL sqlite3_st
30e10 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a ep(sqlite3_stmt*
30e20 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
30e30 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f EF: Number of co
30e40 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c lumns in a resul
30e50 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a t set.** METHOD:
30e60 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a sqlite3_stmt.**
30e70 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
30e80 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 _data_count(P) i
30e90 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
30ea0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 the number of c
30eb0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a olumns in the.**
30ec0 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 current row of
30ed0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f the result set o
30ee0 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 f [prepared stat
30ef0 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 ement] P..** ^If
30f00 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
30f10 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 ent P does not h
30f20 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64 ave results read
30f30 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 y to return.** (
30f40 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 via calls to the
30f50 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
30f60 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 _int | sqlite3_c
30f70 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a olumn_*()] of.**
30f80 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65 interfaces) the
30f90 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 n sqlite3_data_c
30fa0 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20 ount(P) returns
30fb0 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 0..** ^The sqlit
30fc0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 e3_data_count(P)
30fd0 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 routine also re
30fe0 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20 turns 0 if P is
30ff0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a a NULL pointer..
31000 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
31010 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f data_count(P) ro
31020 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 utine returns 0
31030 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 if the previous
31040 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 call to.** [sqli
31050 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 te3_step](P) ret
31060 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f urned [SQLITE_DO
31070 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 NE]. ^The sqlit
31080 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 e3_data_count(P)
31090 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 .** will return
310a0 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 non-zero if prev
310b0 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 ious call to [sq
310c0 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 lite3_step](P) r
310d0 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 eturned.** [SQLI
310e0 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 TE_ROW], except
310f0 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 74 in the case of t
31100 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 he [PRAGMA incre
31110 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a mental_vacuum].*
31120 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77 61 79 * where it alway
31130 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 s returns zero s
31140 69 6e 63 65 20 65 61 63 68 20 73 74 65 70 20 6f ince each step o
31150 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 f that multi-ste
31160 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75 p.** pragma retu
31170 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 rns 0 columns of
31180 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 data..**.** See
31190 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f also: [sqlite3_
311a0 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a column_count()].
311b0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
311c0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
311d0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f sqlite3_data_co
311e0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 unt(sqlite3_stmt
311f0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
31200 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 CAPI3REF: Funda
31210 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 mental Datatypes
31220 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 .** KEYWORDS: SQ
31230 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 LITE_TEXT.**.**
31240 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e ^(Every value in
31250 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 SQLite has one
31260 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e of five fundamen
31270 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a tal datatypes:.*
31280 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
31290 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 > 64-bit signed
312a0 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 integer.** <li>
312b0 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 64-bit IEEE floa
312c0 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 ting point numbe
312d0 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 r.** <li> string
312e0 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a .** <li> BLOB.**
312f0 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f <li> NULL.** </
31300 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ul>)^.**.** Thes
31310 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 e constants are
31320 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f codes for each o
31330 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a f those types..*
31340 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 *.** Note that t
31350 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 he SQLITE_TEXT c
31360 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f onstant was also
31370 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 used in SQLite
31380 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 version 2.** for
31390 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 a completely di
313a0 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e fferent meaning.
313b0 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 Software that
313c0 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f links against bo
313d0 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 th.** SQLite ver
313e0 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 sion 2 and SQLit
313f0 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 e version 3 shou
31400 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 ld use SQLITE3_T
31410 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 EXT, not.** SQLI
31420 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 TE_TEXT..*/.#def
31430 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 ine SQLITE_INTEG
31440 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 ER 1.#define SQ
31450 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a LITE_FLOAT 2.
31460 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 #define SQLITE_B
31470 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e LOB 4.#defin
31480 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 e SQLITE_NULL
31490 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 5.#ifdef SQLIT
314a0 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 E_TEXT.# undef S
314b0 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 QLITE_TEXT.#else
314c0 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 .# define SQLITE
314d0 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 _TEXT 3.#end
314e0 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 if.#define SQLIT
314f0 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f E3_TEXT 3../
31500 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
31510 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f esult Values Fro
31520 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 m A Query.** KEY
31530 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 WORDS: {column a
31540 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d ccess functions}
31550 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
31560 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e te3_stmt.**.** ^
31570 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 These routines r
31580 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f eturn informatio
31590 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 n about a single
315a0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 column of the c
315b0 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 urrent.** result
315c0 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e row of a query.
315d0 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 ^In every case
315e0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
315f0 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 ent is a pointer
31600 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 .** to the [prep
31610 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
31620 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 that is being ev
31630 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 aluated (the [sq
31640 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 lite3_stmt*].**
31650 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 that was returne
31660 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f d from [sqlite3_
31670 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 prepare_v2()] or
31680 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 one of its vari
31690 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 ants).** and the
316a0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
316b0 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 is the index of
316c0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 the column for
316d0 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f which informatio
316e0 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 n.** should be r
316f0 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 eturned. ^The le
31700 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 ftmost column of
31710 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 the result set
31720 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e has the index 0.
31730 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 .** ^The number
31740 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 of columns in th
31750 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 e result can be
31760 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 determined using
31770 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c .** [sqlite3_col
31780 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a umn_count()]..**
31790 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 .** If the SQL s
317a0 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f tatement does no
317b0 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e t currently poin
317c0 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 t to a valid row
317d0 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 , or if the.** c
317e0 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f olumn index is o
317f0 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 ut of range, the
31800 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 result is undef
31810 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 ined..** These r
31820 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 outines may only
31830 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 be called when
31840 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 the most recent
31850 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 call to.** [sqli
31860 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 te3_step()] has
31870 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 returned [SQLITE
31880 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 _ROW] and neithe
31890 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 r.** [sqlite3_re
318a0 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 set()] nor [sqli
318b0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 te3_finalize()]
318c0 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 have been called
318d0 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a subsequently..*
318e0 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 * If any of thes
318f0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 e routines are c
31900 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c alled after [sql
31910 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 ite3_reset()] or
31920 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e .** [sqlite3_fin
31930 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 alize()] or afte
31940 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 r [sqlite3_step(
31950 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a )] has returned.
31960 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 ** something oth
31970 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f er than [SQLITE_
31980 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 ROW], the result
31990 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e s are undefined.
319a0 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f .** If [sqlite3_
319b0 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 step()] or [sqli
319c0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 te3_reset()] or
319d0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
319e0 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c e()].** are call
319f0 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 ed from a differ
31a00 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 ent thread while
31a10 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f any of these ro
31a20 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 utines.** are pe
31a30 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 nding, then the
31a40 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 results are unde
31a50 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 fined..**.** ^Th
31a60 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e e sqlite3_column
31a70 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 _type() routine
31a80 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b returns the.** [
31a90 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c SQLITE_INTEGER |
31aa0 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 datatype code]
31ab0 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 for the initial
31ac0 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 data type.** of
31ad0 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d the result colum
31ae0 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 n. ^The returne
31af0 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f d value is one o
31b00 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 f [SQLITE_INTEGE
31b10 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 R],.** [SQLITE_F
31b20 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 LOAT], [SQLITE_T
31b30 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c EXT], [SQLITE_BL
31b40 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f OB], or [SQLITE_
31b50 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 NULL]. The valu
31b60 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 e.** returned by
31b70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
31b80 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d type() is only m
31b90 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 eaningful if no
31ba0 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 type.** conversi
31bb0 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 ons have occurre
31bc0 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62 d as described b
31bd0 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 elow. After a t
31be0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a ype conversion,.
31bf0 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 ** the value ret
31c00 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 urned by sqlite3
31c10 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 _column_type() i
31c20 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 s undefined. Fu
31c30 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 ture.** versions
31c40 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 of SQLite may c
31c50 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 hange the behavi
31c60 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f or of sqlite3_co
31c70 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 lumn_type().** f
31c80 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 ollowing a type
31c90 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a conversion..**.*
31ca0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 * ^If the result
31cb0 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 is a BLOB or UT
31cc0 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 F-8 string then
31cd0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 the sqlite3_colu
31ce0 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f mn_bytes().** ro
31cf0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 utine returns th
31d00 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
31d10 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f s in that BLOB o
31d20 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 r string..** ^If
31d30 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 the result is a
31d40 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 UTF-16 string,
31d50 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c then sqlite3_col
31d60 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 umn_bytes() conv
31d70 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 erts.** the stri
31d80 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 ng to UTF-8 and
31d90 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 then returns the
31da0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
31db0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 ..** ^If the res
31dc0 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 ult is a numeric
31dd0 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 value then sqli
31de0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
31df0 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 () uses.** [sqli
31e00 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 te3_snprintf()]
31e10 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 to convert that
31e20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 value to a UTF-8
31e30 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 string and retu
31e40 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 rns.** the numbe
31e50 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 r of bytes in th
31e60 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 at string..** ^I
31e70 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 f the result is
31e80 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 NULL, then sqlit
31e90 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
31ea0 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a ) returns zero..
31eb0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 **.** ^If the re
31ec0 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f sult is a BLOB o
31ed0 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 r UTF-16 string
31ee0 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 then the sqlite3
31ef0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
31f00 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 ).** routine ret
31f10 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
31f20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 of bytes in that
31f30 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e BLOB or string.
31f40 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 .** ^If the resu
31f50 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 lt is a UTF-8 st
31f60 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 ring, then sqlit
31f70 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
31f80 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 6() converts.**
31f90 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 the string to UT
31fa0 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 F-16 and then re
31fb0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
31fc0 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 of bytes..** ^I
31fd0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 f the result is
31fe0 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 a numeric value
31ff0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c then sqlite3_col
32000 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 umn_bytes16() us
32010 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 es.** [sqlite3_s
32020 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f nprintf()] to co
32030 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 nvert that value
32040 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 to a UTF-16 str
32050 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a ing and returns.
32060 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ** the number of
32070 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 bytes in that s
32080 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 tring..** ^If th
32090 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c e result is NULL
320a0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 , then sqlite3_c
320b0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 olumn_bytes16()
320c0 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a returns zero..**
320d0 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 .** ^The values
320e0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c returned by [sql
320f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
32100 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 s()] and .** [sq
32110 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
32120 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 es16()] do not i
32130 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 nclude the zero
32140 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 terminators at t
32150 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 he end.** of the
32160 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 string. ^For c
32170 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 larity: the valu
32180 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a es returned by.*
32190 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d * [sqlite3_colum
321a0 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b n_bytes()] and [
321b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
321c0 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 ytes16()] are th
321d0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 e number of.** b
321e0 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 ytes in the stri
321f0 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 ng, not the numb
32200 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 er of characters
32210 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 ..**.** ^Strings
32220 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c returned by sql
32230 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
32240 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 () and sqlite3_c
32250 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a olumn_text16(),.
32260 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 ** even empty st
32270 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 rings, are alway
32280 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 s zero-terminate
32290 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a d. ^The return.
322a0 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 ** value from sq
322b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f lite3_column_blo
322c0 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c b() for a zero-l
322d0 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 ength BLOB is a
322e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a NULL pointer..**
322f0 0a 2a 2a 20 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c .** <b>Warning:<
32300 2f 62 3e 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 /b> ^The object
32310 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c returned by [sql
32320 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 ite3_column_valu
32330 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 e()] is an.** [u
32340 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
32350 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
32360 2e 20 20 49 6e 20 61 20 6d 75 6c 74 69 74 68 72 . In a multithr
32370 65 61 64 65 64 20 65 6e 76 69 72 6f 6e 6d 65 6e eaded environmen
32380 74 2c 0a 2a 2a 20 61 6e 20 75 6e 70 72 6f 74 65 t,.** an unprote
32390 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
323a0 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 6f 6e ue object may on
323b0 6c 79 20 62 65 20 75 73 65 64 20 73 61 66 65 6c ly be used safel
323c0 79 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 y with.** [sqlit
323d0 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d e3_bind_value()]
323e0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 and [sqlite3_re
323f0 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a sult_value()]..*
32400 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 * If the [unprot
32410 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
32420 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 lue] object retu
32430 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 rned by.** [sqli
32440 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 te3_column_value
32450 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 ()] is used in a
32460 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e ny other way, in
32470 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a cluding calls.**
32480 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b to routines lik
32490 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 e [sqlite3_value
324a0 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 _int()], [sqlite
324b0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 3_value_text()],
324c0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f .** or [sqlite3_
324d0 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 value_bytes()],
324e0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 the behavior is
324f0 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 0a not threadsafe..
32500 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
32510 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 ines attempt to
32520 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 convert the valu
32530 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 e where appropri
32540 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 ate. ^For.** ex
32550 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e ample, if the in
32560 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 ternal represent
32570 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 ation is FLOAT a
32580 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 nd a text result
32590 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 .** is requested
325a0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 , [sqlite3_snpri
325b0 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 ntf()] is used i
325c0 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 nternally to per
325d0 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 form the.** conv
325e0 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 ersion automatic
325f0 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c ally. ^(The fol
32600 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 lowing table det
32610 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 ails the convers
32620 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 ions.** that are
32630 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 applied:.**.**
32640 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 <blockquote>.**
32650 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 <table border="1
32660 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 ">.** <tr><th> I
32670 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 nternal<br>Type
32680 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 <th> Requested<b
32690 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e r>Type <th> Con
326a0 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 version.**.** <t
326b0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 r><td> NULL
326c0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c <td> INTEGER <
326d0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a td> Result is 0.
326e0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c ** <tr><td> NUL
326f0 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 L <td> FLOAT
32700 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 <td> Result
32710 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 is 0.0.** <tr><t
32720 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e d> NULL <td>
32730 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 TEXT <td>
32740 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c Result is a NULL
32750 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e pointer.** <tr>
32760 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 <td> NULL <t
32770 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 d> BLOB <td
32780 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 > Result is a NU
32790 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 LL pointer.** <t
327a0 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 r><td> INTEGER
327b0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c <td> FLOAT <
327c0 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d td> Convert from
327d0 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 integer to floa
327e0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e t.** <tr><td> IN
327f0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 TEGER <td> TE
32800 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 XT <td> ASCII
32810 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 rendering of th
32820 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 e integer.** <tr
32830 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c ><td> INTEGER <
32840 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 td> BLOB <t
32850 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 d> Same as INTEG
32860 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e ER->TEXT.** <tr>
32870 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 <td> FLOAT <t
32880 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 d> INTEGER <td
32890 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 > [CAST] to INTE
328a0 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 GER.** <tr><td>
328b0 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 FLOAT <td>
328c0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 TEXT <td> ASC
328d0 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 II rendering of
328e0 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 the float.** <tr
328f0 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c ><td> FLOAT <
32900 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 td> BLOB <t
32910 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f d> [CAST] to BLO
32920 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 B.** <tr><td> T
32930 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 EXT <td> INTE
32940 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 GER <td> [CAST
32950 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 ] to INTEGER.**
32960 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 <tr><td> TEXT
32970 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 <td> FLOAT
32980 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 <td> [CAST] to
32990 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e REAL.** <tr><td>
329a0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 TEXT <td>
329b0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f BLOB <td> No
329c0 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c change.** <tr><
329d0 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 td> BLOB <td
329e0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e > INTEGER <td>
329f0 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 [CAST] to INTEG
32a00 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 ER.** <tr><td>
32a10 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c BLOB <td> FL
32a20 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 OAT <td> [CAS
32a30 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 T] to REAL.** <t
32a40 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 r><td> BLOB
32a50 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c <td> TEXT <
32a60 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 td> Add a zero t
32a70 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 erminator if nee
32a80 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a ded.** </table>.
32a90 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e ** </blockquote>
32aa0 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 )^.**.** Note th
32ab0 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e at when type con
32ac0 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 versions occur,
32ad0 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 pointers returne
32ae0 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 d by prior.** ca
32af0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 lls to sqlite3_c
32b00 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 olumn_blob(), sq
32b10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
32b20 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 t(), and/or.** s
32b30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
32b40 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e xt16() may be in
32b50 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 validated..** Ty
32b60 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 pe conversions a
32b70 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c nd pointer inval
32b80 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f idations might o
32b90 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 ccur.** in the f
32ba0 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a ollowing cases:.
32bb0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
32bc0 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 i> The initial c
32bd0 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 ontent is a BLOB
32be0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c and sqlite3_col
32bf0 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a umn_text() or.**
32c00 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f sqlite3_co
32c10 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 lumn_text16() is
32c20 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f called. A zero
32c30 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 -terminator migh
32c40 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 t.** need t
32c50 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 o be added to th
32c60 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a e string.</li>.*
32c70 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 * <li> The initi
32c80 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 al content is UT
32c90 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c F-8 text and sql
32ca0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
32cb0 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 s16() or.**
32cc0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
32cd0 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c text16() is call
32ce0 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 ed. The content
32cf0 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 must be convert
32d00 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 ed.** to UT
32d10 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c F-16.</li>.** <l
32d20 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 i> The initial c
32d30 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 ontent is UTF-16
32d40 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 text and sqlite
32d50 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
32d60 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 or.** sqli
32d70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
32d80 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 ) is called. Th
32d90 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 e content must b
32da0 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 e converted.**
32db0 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c to UTF-8.</l
32dc0 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a i>.** </ul>.**.*
32dd0 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 * ^Conversions b
32de0 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 etween UTF-16be
32df0 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 and UTF-16le are
32e00 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 always done in
32e10 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 place and do.**
32e20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 not invalidate a
32e30 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 prior pointer,
32e40 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 though of course
32e50 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 the content of
32e60 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 the buffer.** th
32e70 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 at the prior poi
32e80 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 20 nter references
32e90 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d will have been m
32ea0 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 odified. Other
32eb0 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 kinds.** of conv
32ec0 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 ersion are done
32ed0 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 in place when it
32ee0 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 is possible, bu
32ef0 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 t sometimes they
32f00 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 .** are not poss
32f10 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 ible and in thos
32f20 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f e cases prior po
32f30 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c inters are inval
32f40 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 idated..**.** Th
32f50 65 20 73 61 66 65 73 74 20 70 6f 6c 69 63 79 20 e safest policy
32f60 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 is to invoke the
32f70 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 se routines.** i
32f80 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c n one of the fol
32f90 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a lowing ways:.**.
32fa0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e ** <ul>.** <li>
32fb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
32fc0 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 ext() followed b
32fd0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e y sqlite3_column
32fe0 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a _bytes()</li>.**
32ff0 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f <li>sqlite3_co
33000 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c lumn_blob() foll
33010 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f owed by sqlite3_
33020 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f column_bytes()</
33030 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 li>.** <li>sqli
33040 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
33050 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6() followed by
33060 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
33070 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a ytes16()</li>.**
33080 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 </ul>.**.** In
33090 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 other words, you
330a0 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c should call sql
330b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
330c0 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 (),.** sqlite3_c
330d0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 olumn_blob(), or
330e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
330f0 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74 text16() first t
33100 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 o force the resu
33110 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 lt.** into the d
33120 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 esired format, t
33130 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 hen invoke sqlit
33140 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
33150 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f ) or.** sqlite3_
33160 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
33170 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a to find the siz
33180 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e e of the result.
33190 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c Do not mix cal
331a0 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 ls.** to sqlite3
331b0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f _column_text() o
331c0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e r sqlite3_column
331d0 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c _blob() with cal
331e0 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 ls to.** sqlite3
331f0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
33200 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 ), and do not mi
33210 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 x calls to sqlit
33220 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
33230 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 ().** with calls
33240 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 to sqlite3_colu
33250 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a mn_bytes()..**.*
33260 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 * ^The pointers
33270 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c returned are val
33280 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 id until a type
33290 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 conversion occur
332a0 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 s as.** describe
332b0 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 d above, or unti
332c0 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 l [sqlite3_step(
332d0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 )] or [sqlite3_r
332e0 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 eset()] or.** [s
332f0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
33300 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e )] is called. ^
33310 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 The memory space
33320 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 used to hold st
33330 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f rings.** and BLO
33340 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f Bs is freed auto
33350 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c matically. Do <
33360 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 70 61 73 73 em>not</em> pass
33370 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 the pointers re
33380 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b turned.** from [
33390 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
333a0 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 lob()], [sqlite3
333b0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c _column_text()],
333c0 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 etc. into.** [s
333d0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a qlite3_free()]..
333e0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d **.** ^(If a mem
333f0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 ory allocation e
33400 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 rror occurs duri
33410 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f ng the evaluatio
33420 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 n of any.** of t
33430 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 hese routines, a
33440 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 default value i
33450 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 s returned. The
33460 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a default value.*
33470 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 * is either the
33480 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 integer 0, the f
33490 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 loating point nu
334a0 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e mber 0.0, or a N
334b0 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 ULL.** pointer.
334c0 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c Subsequent call
334d0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 s to [sqlite3_er
334e0 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 rcode()] will re
334f0 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f turn.** [SQLITE_
33500 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c NOMEM].)^.*/.SQL
33510 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f ITE_API const vo
33520 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 id *SQLITE_STDCA
33530 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d LL sqlite3_colum
33540 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 n_blob(sqlite3_s
33550 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
33560 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
33570 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
33580 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
33590 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 tes(sqlite3_stmt
335a0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 *, int iCol);.SQ
335b0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
335c0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
335d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
335e0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
335f0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c , int iCol);.SQL
33600 49 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 53 ITE_API double S
33610 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
33620 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 lite3_column_dou
33630 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ble(sqlite3_stmt
33640 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 *, int iCol);.SQ
33650 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
33660 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
33670 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 te3_column_int(s
33680 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
33690 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f t iCol);.SQLITE_
336a0 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 API sqlite3_int6
336b0 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 4 SQLITE_STDCALL
336c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
336d0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 int64(sqlite3_st
336e0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
336f0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
33700 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a unsigned char *
33710 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
33720 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
33730 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a xt(sqlite3_stmt*
33740 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c , int iCol);.SQL
33750 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f ITE_API const vo
33760 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 id *SQLITE_STDCA
33770 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d LL sqlite3_colum
33780 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 n_text16(sqlite3
33790 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
337a0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
337b0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
337c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
337d0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d type(sqlite3_stm
337e0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 t*, int iCol);.S
337f0 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 QLITE_API sqlite
33800 33 5f 76 61 6c 75 65 20 2a 53 51 4c 49 54 45 5f 3_value *SQLITE_
33810 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
33820 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c column_value(sql
33830 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
33840 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 iCol);../*.** CA
33850 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 PI3REF: Destroy
33860 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 A Prepared State
33870 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 44 ment Object.** D
33880 45 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 ESTRUCTOR: sqlit
33890 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 e3_stmt.**.** ^T
338a0 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c he sqlite3_final
338b0 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 ize() function i
338c0 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 s called to dele
338d0 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 te a [prepared s
338e0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 tatement]..** ^I
338f0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e f the most recen
33900 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 t evaluation of
33910 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e the statement en
33920 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 countered no err
33930 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 ors.** or if the
33940 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 statement is ne
33950 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 ver been evaluat
33960 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 ed, then sqlite3
33970 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 _finalize() retu
33980 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b rns.** SQLITE_OK
33990 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 . ^If the most
339a0 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f recent evaluatio
339b0 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 n of statement S
339c0 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a failed, then.**
339d0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a sqlite3_finaliz
339e0 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 e(S) returns the
339f0 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 appropriate [er
33a00 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 ror code] or.**
33a10 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 [extended error
33a20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 code]..**.** ^Th
33a30 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 e sqlite3_finali
33a40 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 ze(S) routine ca
33a50 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 n be called at a
33a60 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a ny point during.
33a70 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c ** the life cycl
33a80 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 e of [prepared s
33a90 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 tatement] S:.**
33aa0 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 before statement
33ab0 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 S is ever evalu
33ac0 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f ated, after.** o
33ad0 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 ne or more calls
33ae0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 to [sqlite3_res
33af0 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 et()], or after
33b00 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b any call.** to [
33b10 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
33b20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 regardless of wh
33b30 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 ether or not the
33b40 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a statement has.*
33b50 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 * completed exec
33b60 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e ution..**.** ^In
33b70 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 voking sqlite3_f
33b80 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e inalize() on a N
33b90 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 ULL pointer is a
33ba0 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e harmless no-op.
33bb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 .**.** The appli
33bc0 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 cation must fina
33bd0 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 lize every [prep
33be0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
33bf0 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 in order to avoi
33c00 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 d.** resource le
33c10 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 aks. It is a gr
33c20 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 ievous error for
33c30 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
33c40 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a to try to use.*
33c50 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 * a prepared sta
33c60 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 tement after it
33c70 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a has been finaliz
33c80 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 ed. Any use of
33c90 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 a prepared.** st
33ca0 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 atement after it
33cb0 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 has been finali
33cc0 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 zed can result i
33cd0 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a n undefined and.
33ce0 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 ** undesirable b
33cf0 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 ehavior such as
33d00 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 segfaults and he
33d10 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a ap corruption..*
33d20 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
33d30 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
33d40 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
33d50 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 (sqlite3_stmt *p
33d60 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 Stmt);../*.** CA
33d70 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 PI3REF: Reset A
33d80 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 Prepared Stateme
33d90 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4d 45 54 nt Object.** MET
33da0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d HOD: sqlite3_stm
33db0 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 t.**.** The sqli
33dc0 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 te3_reset() func
33dd0 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 tion is called t
33de0 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 o reset a [prepa
33df0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a red statement].*
33e00 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f * object back to
33e10 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 its initial sta
33e20 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 te, ready to be
33e30 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 re-executed..**
33e40 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 ^Any SQL stateme
33e50 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 nt variables tha
33e60 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 t had values bou
33e70 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 nd to them using
33e80 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 .** the [sqlite3
33e90 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c _bind_blob | sql
33ea0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 ite3_bind_*() AP
33eb0 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 I] retain their
33ec0 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b values..** Use [
33ed0 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 sqlite3_clear_bi
33ee0 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 ndings()] to res
33ef0 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e et the bindings.
33f00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c .**.** ^The [sql
33f10 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 ite3_reset(S)] i
33f20 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20 nterface resets
33f30 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
33f40 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 atement] S.** ba
33f50 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e ck to the beginn
33f60 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 ing of its progr
33f70 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 am..**.** ^If th
33f80 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 e most recent ca
33f90 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 ll to [sqlite3_s
33fa0 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a tep(S)] for the.
33fb0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ** [prepared sta
33fc0 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e tement] S return
33fd0 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 ed [SQLITE_ROW]
33fe0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d or [SQLITE_DONE]
33ff0 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 ,.** or if [sqli
34000 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 te3_step(S)] has
34010 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 never before be
34020 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a en called on S,.
34030 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 ** then [sqlite3
34040 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 _reset(S)] retur
34050 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a ns [SQLITE_OK]..
34060 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f **.** ^If the mo
34070 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 st recent call t
34080 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 o [sqlite3_step(
34090 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b S)] for the.** [
340a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
340b0 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 nt] S indicated
340c0 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a an error, then.*
340d0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 * [sqlite3_reset
340e0 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 (S)] returns an
340f0 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 appropriate [err
34100 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 or code]..**.**
34110 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 ^The [sqlite3_re
34120 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 set(S)] interfac
34130 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 e does not chang
34140 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 e the values.**
34150 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f of any [sqlite3_
34160 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e bind_blob|bindin
34170 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 gs] on the [prep
34180 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
34190 53 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 S..*/.SQLITE_API
341a0 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
341b0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 73 65 ALL sqlite3_rese
341c0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a t(sqlite3_stmt *
341d0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 pStmt);../*.** C
341e0 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 API3REF: Create
341f0 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 Or Redefine SQL
34200 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 Functions.** KEY
34210 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e WORDS: {function
34220 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e creation routin
34230 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a es}.** KEYWORDS:
34240 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 {application-de
34250 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 fined SQL functi
34260 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a on}.** KEYWORDS:
34270 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 {application-de
34280 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 fined SQL functi
34290 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 ons}.** METHOD:
342a0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 sqlite3.**.** ^T
342b0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 hese functions (
342c0 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f collectively kno
342d0 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 wn as "function
342e0 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 creation routine
342f0 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 s").** are used
34300 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 to add SQL funct
34310 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 ions or aggregat
34320 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e es or to redefin
34330 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a e the behavior.*
34340 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 * of existing SQ
34350 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 L functions or a
34360 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 ggregates. The
34370 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 only differences
34380 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 between.** thes
34390 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 e routines are t
343a0 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 he text encoding
343b0 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a expected for.**
343c0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 the second para
343d0 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 meter (the name
343e0 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 of the function
343f0 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a being created).*
34400 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e * and the presen
34410 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 ce or absence of
34420 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 a destructor ca
34430 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 llback for.** th
34440 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 e application da
34450 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a ta pointer..**.*
34460 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 * ^The first par
34470 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 ameter is the [d
34480 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
34490 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 on] to which the
344a0 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e SQL.** function
344b0 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e is to be added.
344c0 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 ^If an applica
344d0 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 tion uses more t
344e0 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 han one database
344f0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 .** connection t
34500 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d hen application-
34510 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
34520 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 tions must be ad
34530 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 ded.** to each d
34540 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
34550 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a on separately..*
34560 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 *.** ^The second
34570 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
34580 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 e name of the SQ
34590 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 L function to be
345a0 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 created or.** r
345b0 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 edefined. ^The
345c0 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 length of the na
345d0 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f me is limited to
345e0 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 255 bytes in a
345f0 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 UTF-8.** represe
34600 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 ntation, exclusi
34610 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 ve of the zero-t
34620 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 erminator. ^Not
34630 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a e that the name.
34640 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 ** length limit
34650 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 is in UTF-8 byte
34660 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 s, not character
34670 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 s nor UTF-16 byt
34680 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 es. .** ^Any at
34690 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 tempt to create
346a0 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 a function with
346b0 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a a longer name.**
346c0 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 will result in
346d0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 [SQLITE_MISUSE]
346e0 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a being returned..
346f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 **.** ^The third
34700 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 parameter (nArg
34710 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 ).** is the numb
34720 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 er of arguments
34730 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e that the SQL fun
34740 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 ction or.** aggr
34750 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 egate takes. ^If
34760 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 this parameter
34770 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 is -1, then the
34780 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a SQL function or.
34790 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 ** aggregate may
347a0 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 take any number
347b0 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 of arguments be
347c0 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 tween 0 and the
347d0 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 limit.** set by
347e0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 [sqlite3_limit](
347f0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 [SQLITE_LIMIT_FU
34800 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 NCTION_ARG]). I
34810 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 f the third.** p
34820 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 arameter is less
34830 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 than -1 or grea
34840 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 ter than 127 the
34850 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 n the behavior i
34860 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a s.** undefined..
34870 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 **.** ^The fourt
34880 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 h parameter, eTe
34890 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 xtRep, specifies
348a0 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 what.** [SQLITE
348b0 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 _UTF8 | text enc
348c0 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 oding] this SQL
348d0 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 function prefers
348e0 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 for.** its para
348f0 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61 70 70 meters. The app
34900 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 lication should
34910 73 65 74 20 74 68 69 73 20 70 61 72 61 6d 65 74 set this paramet
34920 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 er to.** [SQLITE
34930 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68 65 _UTF16LE] if the
34940 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d function implem
34950 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 entation invokes
34960 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 .** [sqlite3_va
34970 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d 20 lue_text16le()]
34980 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20 on an input, or
34990 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d [SQLITE_UTF16BE]
349a0 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 if the.** imple
349b0 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 mentation invoke
349c0 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 s [sqlite3_value
349d0 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e 20 _text16be()] on
349e0 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 an input, or.**
349f0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 69 [SQLITE_UTF16] i
34a00 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 f [sqlite3_value
34a10 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20 75 73 _text16()] is us
34a20 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 ed, or [SQLITE_U
34a30 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73 TF8].** otherwis
34a40 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53 51 e. ^The same SQ
34a50 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 L function may b
34a60 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c e registered mul
34a70 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69 6e tiple times usin
34a80 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20 70 g.** different p
34a90 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e referred text en
34aa0 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64 69 codings, with di
34ab0 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e fferent implemen
34ac0 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 tations for.** e
34ad0 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a ach encoding..**
34ae0 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 ^When multiple
34af0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
34b00 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 of the same func
34b10 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 tion are availab
34b20 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 le, SQLite.** wi
34b30 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 ll pick the one
34b40 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 that involves th
34b50 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f e least amount o
34b60 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f f data conversio
34b70 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f n..**.** ^The fo
34b80 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6d urth parameter m
34b90 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65 ay optionally be
34ba0 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c 49 ORed with [SQLI
34bb0 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 TE_DETERMINISTIC
34bc0 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74 ].** to signal t
34bd0 68 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f 6e hat the function
34be0 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 will always ret
34bf0 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65 73 urn the same res
34c00 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65 ult given.** the
34c10 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69 74 same inputs wit
34c20 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51 4c hin a single SQL
34c30 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 statement. Mos
34c40 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 t SQL functions
34c50 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69 are.** determini
34c60 73 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c 74 stic. The built
34c70 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 -in [random()] S
34c80 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 QL function is a
34c90 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a n example of a.*
34ca0 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 * function that
34cb0 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69 is not determini
34cc0 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69 74 stic. The SQLit
34cd0 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 e query planner
34ce0 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 is able to.** pe
34cf0 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c rform additional
34d00 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f optimizations o
34d10 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 20 n deterministic
34d20 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73 functions, so us
34d30 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c e.** of the [SQL
34d40 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 ITE_DETERMINISTI
34d50 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f 6d C] flag is recom
34d60 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f 73 mended where pos
34d70 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 sible..**.** ^(T
34d80 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 he fifth paramet
34d90 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 er is an arbitra
34da0 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 ry pointer. The
34db0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
34dc0 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 of the.** functi
34dd0 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 on can gain acce
34de0 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 ss to this point
34df0 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 er using [sqlite
34e00 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 3_user_data()].)
34e10 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 ^.**.** ^The six
34e20 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20 th, seventh and
34e30 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72 eighth parameter
34e40 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 s, xFunc, xStep
34e50 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a and xFinal, are.
34e60 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 ** pointers to C
34e70 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 -language functi
34e80 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 ons that impleme
34e90 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 nt the SQL funct
34ea0 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 ion or.** aggreg
34eb0 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 ate. ^A scalar S
34ec0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 QL function requ
34ed0 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e ires an implemen
34ee0 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 tation of the xF
34ef0 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 unc.** callback
34f00 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 only; NULL point
34f10 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73 ers must be pass
34f20 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20 ed as the xStep
34f30 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 and xFinal.** pa
34f40 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 rameters. ^An ag
34f50 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 gregate SQL func
34f60 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e tion requires an
34f70 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
34f80 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 of xStep.** and
34f90 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 xFinal and NULL
34fa0 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20 pointer must be
34fb0 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 passed for xFunc
34fc0 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 . ^To delete an
34fd0 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 existing.** SQL
34fe0 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 function or aggr
34ff0 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c egate, pass NULL
35000 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c pointers for al
35010 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e l three function
35020 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a .** callbacks..*
35030 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 *.** ^(If the ni
35040 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f nth parameter to
35050 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
35060 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 function_v2() is
35070 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 not NULL,.** th
35080 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63 en it is destruc
35090 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c tor for the appl
350a0 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 ication data poi
350b0 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 nter. .** The de
350c0 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f structor is invo
350d0 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e ked when the fun
350e0 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 ction is deleted
350f0 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e , either by bein
35100 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 g.** overloaded
35110 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 or when the data
35120 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
35130 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 closes.)^.** ^Th
35140 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 e destructor is
35150 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 also invoked if
35160 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 the call to.** s
35170 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
35180 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c nction_v2() fail
35190 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 s..** ^When the
351a0 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 destructor callb
351b0 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68 ack of the tenth
351c0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e parameter is in
351d0 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 voked, it.** is
351e0 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20 passed a single
351f0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 argument which i
35200 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 s a copy of the
35210 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 application data
35220 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 .** pointer whi
35230 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68 ch was the fifth
35240 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
35250 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
35260 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a ction_v2()..**.*
35270 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 * ^It is permitt
35280 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d ed to register m
35290 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e ultiple implemen
352a0 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 tations of the s
352b0 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 ame.** functions
352c0 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e with the same n
352d0 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74 ame but with eit
352e0 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 her differing nu
352f0 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 mbers of.** argu
35300 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 ments or differi
35310 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78 ng preferred tex
35320 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 t encodings. ^S
35330 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a QLite will use.*
35340 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 * the implementa
35350 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 tion that most c
35360 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 losely matches t
35370 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 he way in which
35380 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 the.** SQL funct
35390 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 ion is used. ^A
353a0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d function implem
353b0 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 entation with a
353c0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 non-negative.**
353d0 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 nArg parameter i
353e0 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 s a better match
353f0 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e than a function
35400 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
35410 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 with.** a negati
35420 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e ve nArg. ^A fun
35430 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 ction where the
35440 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 preferred text e
35450 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 ncoding.** match
35460 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 es the database
35470 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 encoding is a be
35480 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 tter.** match th
35490 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 an a function wh
354a0 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 ere the encoding
354b0 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 is different.
354c0 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 .** ^A function
354d0 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 where the encodi
354e0 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 ng difference is
354f0 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 between UTF16le
35500 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 and UTF16be.**
35510 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 is a closer matc
35520 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f h than a functio
35530 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f n where the enco
35540 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 ding difference
35550 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 is.** between UT
35560 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a F8 and UTF16..**
35570 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 .** ^Built-in fu
35580 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f nctions may be o
35590 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 verloaded by new
355a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
355b0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a ined functions..
355c0 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 **.** ^An applic
355d0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
355e0 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 nction is permit
355f0 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 ted to call othe
35600 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 r.** SQLite inte
35610 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 rfaces. However
35620 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 , such calls mus
35630 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 t not.** close t
35640 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
35650 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c ection nor final
35660 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 ize or reset the
35670 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 prepared.** sta
35680 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 tement in which
35690 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 the function is
356a0 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 running..*/.SQLI
356b0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
356c0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
356d0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
356e0 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 n(. sqlite3 *db
356f0 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a ,. const char *
35700 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 zFunctionName,.
35710 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 int nArg,. int
35720 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 eTextRep,. voi
35730 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 d *pApp,. void
35740 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 (*xFunc)(sqlite3
35750 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 _context*,int,sq
35760 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a lite3_value**),.
35770 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 void (*xStep)(
35780 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
35790 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c ,int,sqlite3_val
357a0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a ue**),. void (*
357b0 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f xFinal)(sqlite3_
357c0 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c context*).);.SQL
357d0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 ITE_API int SQLI
357e0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
357f0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
35800 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 on16(. sqlite3
35810 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 *db,. const voi
35820 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 d *zFunctionName
35830 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 ,. int nArg,.
35840 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 int eTextRep,.
35850 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f void *pApp,. vo
35860 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 id (*xFunc)(sqli
35870 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 te3_context*,int
35880 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a ,sqlite3_value**
35890 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 ),. void (*xSte
358a0 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 p)(sqlite3_conte
358b0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f xt*,int,sqlite3_
358c0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 value**),. void
358d0 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 (*xFinal)(sqlit
358e0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a e3_context*).);.
358f0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
35900 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
35910 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
35920 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 ction_v2(. sqli
35930 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 te3 *db,. const
35940 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e char *zFunction
35950 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 Name,. int nArg
35960 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 ,. int eTextRep
35970 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a ,. void *pApp,.
35980 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 void (*xFunc)(
35990 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
359a0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c ,int,sqlite3_val
359b0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a ue**),. void (*
359c0 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 xStep)(sqlite3_c
359d0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 ontext*,int,sqli
359e0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 te3_value**),.
359f0 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 void (*xFinal)(s
35a00 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 qlite3_context*)
35a10 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 ,. void(*xDestr
35a20 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f oy)(void*).);../
35a30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 *.** CAPI3REF: T
35a40 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a ext Encodings.**
35a50 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 .** These consta
35a60 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 nt define intege
35a70 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 r codes that rep
35a80 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f resent the vario
35a90 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 us.** text encod
35aa0 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 ings supported b
35ab0 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 y SQLite..*/.#de
35ac0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 fine SQLITE_UTF8
35ad0 20 20 20 20 20 20 20 20 20 20 20 31 20 20 20 20 1
35ae0 2f 2a 20 49 4d 50 3a 20 52 2d 33 37 35 31 34 2d /* IMP: R-37514-
35af0 33 35 35 36 36 20 2a 2f 0a 23 64 65 66 69 6e 65 35566 */.#define
35b00 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 SQLITE_UTF16LE
35b10 20 20 20 20 20 20 20 32 20 20 20 20 2f 2a 20 49 2 /* I
35b20 4d 50 3a 20 52 2d 30 33 33 37 31 2d 33 37 36 33 MP: R-03371-3763
35b30 37 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 7 */.#define SQL
35b40 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 ITE_UTF16BE
35b50 20 20 20 33 20 20 20 20 2f 2a 20 49 4d 50 3a 20 3 /* IMP:
35b60 52 2d 35 31 39 37 31 2d 33 34 31 35 34 20 2a 2f R-51971-34154 */
35b70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
35b80 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34 UTF16 4
35b90 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 /* Use nativ
35ba0 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a e byte order */.
35bb0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
35bc0 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20 NY 5
35bd0 20 20 20 2f 2a 20 44 65 70 72 65 63 61 74 65 64 /* Deprecated
35be0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
35bf0 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 TE_UTF16_ALIGNED
35c00 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 8 /* sqlite
35c10 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
35c20 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a on only */../*.*
35c30 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 * CAPI3REF: Func
35c40 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a tion Flags.**.**
35c50 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 These constants
35c60 20 6d 61 79 20 62 65 20 4f 52 65 64 20 74 6f 67 may be ORed tog
35c70 65 74 68 65 72 20 77 69 74 68 20 74 68 65 20 0a ether with the .
35c80 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 ** [SQLITE_UTF8
35c90 7c 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 | preferred text
35ca0 20 65 6e 63 6f 64 69 6e 67 5d 20 61 73 20 74 68 encoding] as th
35cb0 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e e fourth argumen
35cc0 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 t.** to [sqlite3
35cd0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
35ce0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 ()], [sqlite3_cr
35cf0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 eate_function16(
35d00 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 )], or.** [sqlit
35d10 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
35d20 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65 on_v2()]..*/.#de
35d30 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 45 fine SQLITE_DETE
35d40 52 4d 49 4e 49 53 54 49 43 20 20 20 20 30 78 38 RMINISTIC 0x8
35d50 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 00../*.** CAPI3R
35d60 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 EF: Deprecated F
35d70 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 unctions.** DEPR
35d80 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 ECATED.**.** The
35d90 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 se functions are
35da0 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 [deprecated].
35db0 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e In order to main
35dc0 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 tain.** backward
35dd0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 s compatibility
35de0 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c with older code,
35df0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 these functions
35e00 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f continue .** to
35e10 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 be supported.
35e20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 However, new app
35e30 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 lications should
35e40 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 avoid.** the us
35e50 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 e of these funct
35e60 69 6f 6e 73 2e 20 20 54 6f 20 65 6e 63 6f 75 72 ions. To encour
35e70 61 67 65 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 age programmers
35e80 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 73 to avoid.** thes
35e90 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 e functions, we
35ea0 77 69 6c 6c 20 6e 6f 74 20 65 78 70 6c 61 69 6e will not explain
35eb0 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a what they do..*
35ec0 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 /.#ifndef SQLITE
35ed0 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 _OMIT_DEPRECATED
35ee0 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 .SQLITE_API SQLI
35ef0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e TE_DEPRECATED in
35f00 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
35f10 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 sqlite3_aggrega
35f20 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 te_count(sqlite3
35f30 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 _context*);.SQLI
35f40 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 TE_API SQLITE_DE
35f50 50 52 45 43 41 54 45 44 20 69 6e 74 20 53 51 4c PRECATED int SQL
35f60 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
35f70 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 te3_expired(sqli
35f80 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 te3_stmt*);.SQLI
35f90 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 TE_API SQLITE_DE
35fa0 50 52 45 43 41 54 45 44 20 69 6e 74 20 53 51 4c PRECATED int SQL
35fb0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
35fc0 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e te3_transfer_bin
35fd0 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 dings(sqlite3_st
35fe0 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d mt*, sqlite3_stm
35ff0 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 t*);.SQLITE_API
36000 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 SQLITE_DEPRECATE
36010 44 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 D int SQLITE_STD
36020 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 67 6c 6f CALL sqlite3_glo
36030 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 bal_recover(void
36040 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 );.SQLITE_API SQ
36050 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 LITE_DEPRECATED
36060 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 void SQLITE_STDC
36070 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74 68 72 65 ALL sqlite3_thre
36080 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 ad_cleanup(void)
36090 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c ;.SQLITE_API SQL
360a0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 ITE_DEPRECATED i
360b0 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c nt SQLITE_STDCAL
360c0 4c 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 L sqlite3_memory
360d0 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 _alarm(void(*)(v
360e0 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 oid*,sqlite3_int
360f0 36 34 2c 69 6e 74 29 2c 0a 20 20 20 20 20 20 20 64,int),.
36100 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 v
36110 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 oid*,sqlite3_int
36120 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 64);.#endif../*.
36130 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 ** CAPI3REF: Obt
36140 61 69 6e 69 6e 67 20 53 51 4c 20 56 61 6c 75 65 aining SQL Value
36150 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c s.** METHOD: sql
36160 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a ite3_value.**.**
36170 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 The C-language
36180 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
36190 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 f SQL functions
361a0 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75 and aggregates u
361b0 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 ses.** this set
361c0 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 of interface rou
361d0 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 tines to access
361e0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 the parameter va
361f0 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 lues on.** the f
36200 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 unction or aggre
36210 67 61 74 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 gate. .**.** Th
36220 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 e xFunc (for sca
36230 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f lar functions) o
36240 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 r xStep (for agg
36250 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 regates) paramet
36260 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 ers.** to [sqlit
36270 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
36280 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 on()] and [sqlit
36290 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
362a0 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e on16()].** defin
362b0 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 e callbacks that
362c0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 implement the S
362d0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 QL functions and
362e0 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 aggregates..**
362f0 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 The 3rd paramete
36300 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 r to these callb
36310 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 acks is an array
36320 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a of pointers to.
36330 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 ** [protected sq
36340 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
36350 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 ects. There is
36360 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c one [sqlite3_val
36370 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a ue] object for.*
36380 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 * each parameter
36390 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 to the SQL func
363a0 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 tion. These rou
363b0 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 tines are used t
363c0 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c o.** extract val
363d0 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 ues from the [sq
363e0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
363f0 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ects..**.** Thes
36400 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 e routines work
36410 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 only with [prote
36420 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
36430 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 ue] objects..**
36440 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 Any attempt to u
36450 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 se these routine
36460 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 s on an [unprote
36470 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
36480 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 ue].** object re
36490 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e sults in undefin
364a0 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a ed behavior..**.
364b0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e ** ^These routin
364c0 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b es work just lik
364d0 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 e the correspond
364e0 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 ing [column acce
364f0 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a ss functions].**
36500 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65 except that the
36510 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 se routines take
36520 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 a single [prote
36530 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
36540 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f ue] object.** po
36550 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 inter instead of
36560 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 a [sqlite3_stmt
36570 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 *] pointer and a
36580 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e n integer column
36590 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e number..**.** ^
365a0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 The sqlite3_valu
365b0 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 e_text16() inter
365c0 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61 20 face extracts a
365d0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a UTF-16 string.**
365e0 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 in the native b
365f0 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 yte-order of the
36600 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 host machine.
36610 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f ^The.** sqlite3_
36620 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 value_text16be()
36630 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c and sqlite3_val
36640 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e ue_text16le() in
36650 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 terfaces.** extr
36660 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e act UTF-16 strin
36670 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e gs as big-endian
36680 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 and little-endi
36690 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e an respectively.
366a0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c .**.** ^(The sql
366b0 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 ite3_value_numer
366c0 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 ic_type() interf
366d0 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 ace attempts to
366e0 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 apply.** numeric
366f0 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 affinity to the
36700 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 value. This me
36710 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 ans that an atte
36720 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 mpt is.** made t
36730 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 o convert the va
36740 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 lue to an intege
36750 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f r or floating po
36760 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 int. If.** such
36770 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 a conversion is
36780 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 possible withou
36790 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d t loss of inform
367a0 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a ation (in other.
367b0 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 ** words, if the
367c0 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 value is a stri
367d0 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 ng that looks li
367e0 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 ke a number).**
367f0 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 then the convers
36800 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 ion is performed
36810 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 . Otherwise no
36820 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 conversion occur
36830 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 s..** The [SQLIT
36840 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 E_INTEGER | data
36850 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 type] after conv
36860 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e ersion is return
36870 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 ed.)^.**.** Plea
36880 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 se pay particula
36890 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 r attention to t
368a0 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65 he fact that the
368b0 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65 pointer returne
368c0 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 d.** from [sqlit
368d0 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d e3_value_blob()]
368e0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 , [sqlite3_value
368f0 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 _text()], or.**
36900 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 [sqlite3_value_t
36910 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 ext16()] can be
36920 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 invalidated by a
36930 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c subsequent call
36940 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
36950 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 value_bytes()],
36960 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 [sqlite3_value_b
36970 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 ytes16()], [sqli
36980 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 te3_value_text()
36990 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 ],.** or [sqlite
369a0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 3_value_text16()
369b0 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 ]..**.** These r
369c0 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 outines must be
369d0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 called from the
369e0 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a same thread as.*
369f0 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 * the SQL functi
36a00 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 on that supplied
36a10 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 the [sqlite3_va
36a20 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 lue*] parameters
36a30 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
36a40 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 const void *SQLI
36a50 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
36a60 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 e3_value_blob(sq
36a70 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 lite3_value*);.S
36a80 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 QLITE_API int SQ
36a90 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
36aa0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 ite3_value_bytes
36ab0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
36ac0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
36ad0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
36ae0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 sqlite3_value_by
36af0 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 tes16(sqlite3_va
36b00 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 lue*);.SQLITE_AP
36b10 49 20 64 6f 75 62 6c 65 20 53 51 4c 49 54 45 5f I double SQLITE_
36b20 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
36b30 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c value_double(sql
36b40 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 ite3_value*);.SQ
36b50 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
36b60 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
36b70 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 te3_value_int(sq
36b80 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 lite3_value*);.S
36b90 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 QLITE_API sqlite
36ba0 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 3_int64 SQLITE_S
36bb0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 TDCALL sqlite3_v
36bc0 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 alue_int64(sqlit
36bd0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 e3_value*);.SQLI
36be0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 TE_API const uns
36bf0 69 67 6e 65 64 20 63 68 61 72 20 2a 53 51 4c 49 igned char *SQLI
36c00 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
36c10 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 e3_value_text(sq
36c20 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 lite3_value*);.S
36c30 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
36c40 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 void *SQLITE_STD
36c50 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c CALL sqlite3_val
36c60 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 ue_text16(sqlite
36c70 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 3_value*);.SQLIT
36c80 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 E_API const void
36c90 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c *SQLITE_STDCALL
36ca0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
36cb0 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f ext16le(sqlite3_
36cc0 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f value*);.SQLITE_
36cd0 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a API const void *
36ce0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
36cf0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
36d00 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 t16be(sqlite3_va
36d10 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 lue*);.SQLITE_AP
36d20 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
36d30 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c CALL sqlite3_val
36d40 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f ue_type(sqlite3_
36d50 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f value*);.SQLITE_
36d60 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 API int SQLITE_S
36d70 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 TDCALL sqlite3_v
36d80 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 alue_numeric_typ
36d90 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a e(sqlite3_value*
36da0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
36db0 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 EF: Obtaining SQ
36dc0 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 L Values.** METH
36dd0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 OD: sqlite3_valu
36de0 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 e.**.** The sqli
36df0 74 65 33 5f 76 61 6c 75 65 5f 73 75 62 74 79 70 te3_value_subtyp
36e00 65 28 56 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 e(V) function re
36e10 74 75 72 6e 73 20 74 68 65 20 73 75 62 74 79 70 turns the subtyp
36e20 65 20 66 6f 72 0a 2a 2a 20 61 6e 20 5b 61 70 70 e for.** an [app
36e30 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
36e40 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 20 61 SQL function] a
36e50 72 67 75 6d 65 6e 74 20 56 2e 20 20 54 68 65 20 rgument V. The
36e60 73 75 62 74 79 70 65 0a 2a 2a 20 69 6e 66 6f 72 subtype.** infor
36e70 6d 61 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 mation can be us
36e80 65 64 20 74 6f 20 70 61 73 73 20 61 20 6c 69 6d ed to pass a lim
36e90 69 74 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 63 ited amount of c
36ea0 6f 6e 74 65 78 74 20 66 72 6f 6d 0a 2a 2a 20 6f ontext from.** o
36eb0 6e 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 ne SQL function
36ec0 74 6f 20 61 6e 6f 74 68 65 72 2e 20 20 55 73 65 to another. Use
36ed0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 the [sqlite3_re
36ee0 73 75 6c 74 5f 73 75 62 74 79 70 65 28 29 5d 0a sult_subtype()].
36ef0 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 73 65 ** routine to se
36f00 74 20 74 68 65 20 73 75 62 74 79 70 65 20 66 6f t the subtype fo
36f10 72 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c r the return val
36f20 75 65 20 6f 66 20 61 6e 20 53 51 4c 20 66 75 6e ue of an SQL fun
36f30 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c ction..**.** SQL
36f40 69 74 65 20 6d 61 6b 65 73 20 6e 6f 20 75 73 65 ite makes no use
36f50 20 6f 66 20 73 75 62 74 79 70 65 20 69 74 73 65 of subtype itse
36f60 6c 66 2e 20 20 49 74 20 6d 65 72 65 6c 79 20 70 lf. It merely p
36f70 61 73 73 65 73 20 74 68 65 20 73 75 62 74 79 70 asses the subtyp
36f80 65 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 72 65 e.** from the re
36f90 73 75 6c 74 20 6f 66 20 6f 6e 65 20 5b 61 70 70 sult of one [app
36fa0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
36fb0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 20 69 SQL function] i
36fc0 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 nto the.** input
36fd0 20 6f 66 20 61 6e 6f 74 68 65 72 2e 0a 2a 2f 0a of another..*/.
36fe0 53 51 4c 49 54 45 5f 41 50 49 20 75 6e 73 69 67 SQLITE_API unsig
36ff0 6e 65 64 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 ned int SQLITE_S
37000 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 TDCALL sqlite3_v
37010 61 6c 75 65 5f 73 75 62 74 79 70 65 28 73 71 6c alue_subtype(sql
37020 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f ite3_value*);../
37030 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
37040 6f 70 79 20 41 6e 64 20 46 72 65 65 20 53 51 4c opy And Free SQL
37050 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f Values.** METHO
37060 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 D: sqlite3_value
37070 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
37080 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 56 29 te3_value_dup(V)
37090 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 interface makes
370a0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b a copy of the [
370b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a sqlite3_value].*
370c0 2a 20 6f 62 6a 65 63 74 20 44 20 61 6e 64 20 72 * object D and r
370d0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
370e0 20 74 6f 20 74 68 61 74 20 63 6f 70 79 2e 20 20 to that copy.
370f0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 ^The [sqlite3_va
37100 6c 75 65 5d 20 72 65 74 75 72 6e 65 64 0a 2a 2a lue] returned.**
37110 20 69 73 20 61 20 5b 70 72 6f 74 65 63 74 65 64 is a [protected
37120 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
37130 6f 62 6a 65 63 74 20 65 76 65 6e 20 69 66 20 74 object even if t
37140 68 65 20 69 6e 70 75 74 20 69 73 20 6e 6f 74 2e he input is not.
37150 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
37160 5f 76 61 6c 75 65 5f 64 75 70 28 56 29 20 69 6e _value_dup(V) in
37170 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
37180 4e 55 4c 4c 20 69 66 20 56 20 69 73 20 4e 55 4c NULL if V is NUL
37190 4c 20 6f 72 20 69 66 20 61 0a 2a 2a 20 6d 65 6d L or if a.** mem
371a0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 ory allocation f
371b0 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ails..**.** ^The
371c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66 sqlite3_value_f
371d0 72 65 65 28 56 29 20 69 6e 74 65 72 66 61 63 65 ree(V) interface
371e0 20 66 72 65 65 73 20 61 6e 20 5b 73 71 6c 69 74 frees an [sqlit
371f0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
37200 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f .** previously o
37210 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
37220 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 lite3_value_dup(
37230 29 5d 2e 20 20 5e 49 66 20 56 20 69 73 20 61 20 )]. ^If V is a
37240 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 NULL pointer.**
37250 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c then sqlite3_val
37260 75 65 5f 66 72 65 65 28 56 29 20 69 73 20 61 20 ue_free(V) is a
37270 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a harmless no-op..
37280 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 */.SQLITE_API SQ
37290 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 LITE_EXPERIMENTA
372a0 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 L sqlite3_value
372b0 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 *SQLITE_STDCALL
372c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 sqlite3_value_du
372d0 70 28 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f p(const sqlite3_
372e0 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f value*);.SQLITE_
372f0 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52 API SQLITE_EXPER
37300 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 53 51 4c IMENTAL void SQL
37310 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
37320 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 73 te3_value_free(s
37330 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
37340 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
37350 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 Obtain Aggregat
37360 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 e Function Conte
37370 78 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 xt.** METHOD: sq
37380 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a lite3_context.**
37390 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 .** Implementati
373a0 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74 65 ons of aggregate
373b0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 SQL functions u
373c0 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 se this.** routi
373d0 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d ne to allocate m
373e0 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e emory for storin
373f0 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a g their state..*
37400 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 *.** ^The first
37410 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 time the sqlite3
37420 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 _aggregate_conte
37430 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 xt(C,N) routine
37440 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f is called .** fo
37450 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61 r a particular a
37460 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f ggregate functio
37470 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c n, SQLite.** all
37480 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f ocates N of memo
37490 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 ry, zeroes out t
374a0 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 hat memory, and
374b0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
374c0 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 r.** to the new
374d0 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f memory. ^On seco
374e0 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e nd and subsequen
374f0 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 t calls to.** sq
37500 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
37510 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 context() for th
37520 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 e same aggregate
37530 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e function instan
37540 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 ce,.** the same
37550 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e buffer is return
37560 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67 ed. Sqlite3_agg
37570 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 regate_context()
37580 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 is normally.**
37590 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 called once for
375a0 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 each invocation
375b0 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 61 6c of the xStep cal
375c0 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f lback and then o
375d0 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 ne.** last time
375e0 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 when the xFinal
375f0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f callback is invo
37600 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 ked. ^(When no
37610 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e rows match.** an
37620 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 aggregate query
37630 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 63 61 , the xStep() ca
37640 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67 llback of the ag
37650 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e gregate function
37660 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
37670 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c on is never call
37680 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 ed and xFinal()
37690 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c is called exactl
376a0 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 y once..** In th
376b0 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74 ose cases, sqlit
376c0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
376d0 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 65 20 text() might be
376e0 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a called for the.*
376f0 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f * first time fro
37700 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 m within xFinal(
37710 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ).)^.**.** ^The
37720 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 sqlite3_aggregat
37730 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 e_context(C,N) r
37740 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 outine returns a
37750 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a 2a NULL pointer .*
37760 2a 20 77 68 65 6e 20 66 69 72 73 74 20 63 61 6c * when first cal
37770 6c 65 64 20 69 66 20 4e 20 69 73 20 6c 65 73 73 led if N is less
37780 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 than or equal t
37790 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d o zero or if a m
377a0 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 emory.** allocat
377b0 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a e error occurs..
377c0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 **.** ^(The amou
377d0 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f nt of space allo
377e0 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 cated by sqlite3
377f0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 _aggregate_conte
37800 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 xt(C,N) is.** de
37810 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 termined by the
37820 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 N parameter on f
37830 69 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 irst successful
37840 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 call. Changing
37850 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 the.** value of
37860 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 N in subsequent
37870 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
37880 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 aggregate_contex
37890 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 t() within.** th
378a0 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 e same aggregate
378b0 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e function instan
378c0 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 ce will not resi
378d0 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a ze the memory.**
378e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 20 allocation.)^
378f0 57 69 74 68 69 6e 20 74 68 65 20 78 46 69 6e 61 Within the xFina
37900 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20 69 l callback, it i
37910 73 20 63 75 73 74 6f 6d 61 72 79 20 74 6f 20 73 s customary to s
37920 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 6c et.** N=0 in cal
37930 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 ls to sqlite3_ag
37940 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 gregate_context(
37950 43 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e 6f 20 C,N) so that no
37960 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20 6d 65 .** pointless me
37970 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 mory allocations
37980 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 occur..**.** ^S
37990 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 QLite automatica
379a0 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d 65 lly frees the me
379b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 mory allocated b
379c0 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 y .** sqlite3_ag
379d0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 gregate_context(
379e0 29 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 ) when the aggre
379f0 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c gate query concl
37a00 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 udes..**.** The
37a10 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
37a20 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f must be a copy o
37a30 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 f the.** [sqlite
37a40 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 3_context | SQL
37a50 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 function context
37a60 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69 ] that is the fi
37a70 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a rst parameter.**
37a80 20 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72 to the xStep or
37a90 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b xFinal callback
37aa0 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d routine that im
37ab0 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 plements the agg
37ac0 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 regate.** functi
37ad0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 on..**.** This r
37ae0 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 outine must be c
37af0 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 alled from the s
37b00 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 ame thread in wh
37b10 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 ich.** the aggre
37b20 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f gate SQL functio
37b30 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f n is running..*/
37b40 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
37b50 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c *SQLITE_STDCALL
37b60 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 sqlite3_aggrega
37b70 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 te_context(sqlit
37b80 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 e3_context*, int
37b90 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a nBytes);../*.**
37ba0 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 CAPI3REF: User
37bb0 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f Data For Functio
37bc0 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 ns.** METHOD: sq
37bd0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a lite3_context.**
37be0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
37bf0 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 _user_data() int
37c00 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 erface returns a
37c10 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 copy of.** the
37c20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 pointer that was
37c30 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70 the pUserData p
37c40 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 arameter (the 5t
37c50 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 h parameter).**
37c60 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
37c70 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 create_function(
37c80 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 )].** and [sqlit
37c90 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
37ca0 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 on16()] routines
37cb0 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 that originally
37cc0 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 .** registered t
37cd0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 he application d
37ce0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e efined function.
37cf0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
37d00 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c ine must be call
37d10 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 ed from the same
37d20 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 thread in which
37d30 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 .** the applicat
37d40 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
37d50 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e tion is running.
37d60 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 .*/.SQLITE_API v
37d70 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 oid *SQLITE_STDC
37d80 41 4c 4c 20 73 71 6c 69 74 65 33 5f 75 73 65 72 ALL sqlite3_user
37d90 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f _data(sqlite3_co
37da0 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 ntext*);../*.**
37db0 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 CAPI3REF: Databa
37dc0 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f se Connection Fo
37dd0 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d r Functions.** M
37de0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 ETHOD: sqlite3_c
37df0 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 ontext.**.** ^Th
37e00 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 e sqlite3_contex
37e10 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e t_db_handle() in
37e20 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
37e30 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 a copy of.** the
37e40 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
37e50 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
37e60 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 tion] (the 1st p
37e70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 arameter).** of
37e80 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 the [sqlite3_cre
37e90 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a ate_function()].
37ea0 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ** and [sqlite3_
37eb0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 create_function1
37ec0 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 6()] routines th
37ed0 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a at originally.**
37ee0 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 registered the
37ef0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 application defi
37f00 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f ned function..*/
37f10 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 .SQLITE_API sqli
37f20 74 65 33 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 te3 *SQLITE_STDC
37f30 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ALL sqlite3_cont
37f40 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 ext_db_handle(sq
37f50 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b lite3_context*);
37f60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
37f70 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c : Function Auxil
37f80 69 61 72 79 20 44 61 74 61 0a 2a 2a 20 4d 45 54 iary Data.** MET
37f90 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e HOD: sqlite3_con
37fa0 74 65 78 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 text.**.** These
37fb0 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 functions may b
37fc0 65 20 75 73 65 64 20 62 79 20 28 6e 6f 6e 2d 61 e used by (non-a
37fd0 67 67 72 65 67 61 74 65 29 20 53 51 4c 20 66 75 ggregate) SQL fu
37fe0 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 nctions to.** as
37ff0 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 sociate metadata
38000 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 with argument v
38010 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 alues. If the sa
38020 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 me value is pass
38030 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c ed to.** multipl
38040 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 e invocations of
38050 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 the same SQL fu
38060 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 nction during qu
38070 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 ery execution, u
38080 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 nder.** some cir
38090 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 cumstances the a
380a0 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 ssociated metada
380b0 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 ta may be preser
380c0 76 65 64 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 ved. An example
380d0 0a 2a 2a 20 6f 66 20 77 68 65 72 65 20 74 68 69 .** of where thi
380e0 73 20 6d 69 67 68 74 20 62 65 20 75 73 65 66 75 s might be usefu
380f0 6c 20 69 73 20 69 6e 20 61 20 72 65 67 75 6c 61 l is in a regula
38100 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 r-expression mat
38110 63 68 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f ching.** functio
38120 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 n. The compiled
38130 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 version of the r
38140 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f egular expressio
38150 6e 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 n can be stored
38160 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 as.** metadata a
38170 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 ssociated with t
38180 68 65 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e he pattern strin
38190 67 2e 20 20 0a 2a 2a 20 54 68 65 6e 20 61 73 20 g. .** Then as
381a0 6c 6f 6e 67 20 61 73 20 74 68 65 20 70 61 74 74 long as the patt
381b0 65 72 6e 20 73 74 72 69 6e 67 20 72 65 6d 61 69 ern string remai
381c0 6e 73 20 74 68 65 20 73 61 6d 65 2c 0a 2a 2a 20 ns the same,.**
381d0 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 the compiled reg
381e0 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 ular expression
381f0 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e can be reused on
38200 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 multiple.** inv
38210 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 ocations of the
38220 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a same function..*
38230 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
38240 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 3_get_auxdata()
38250 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
38260 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 s a pointer to t
38270 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 he metadata.** a
38280 73 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 ssociated by the
38290 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 sqlite3_set_aux
382a0 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 data() function
382b0 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 with the Nth arg
382c0 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 ument.** value t
382d0 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f o the applicatio
382e0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
382f0 6f 6e 2e 20 5e 49 66 20 74 68 65 72 65 20 69 73 on. ^If there is
38300 20 6e 6f 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 no metadata.**
38310 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
38320 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 the function arg
38330 75 6d 65 6e 74 2c 20 74 68 69 73 20 73 71 6c 69 ument, this sqli
38340 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 te3_get_auxdata(
38350 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 ) interface.** r
38360 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f eturns a NULL po
38370 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 inter..**.** ^Th
38380 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 e sqlite3_set_au
38390 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 69 xdata(C,N,P,X) i
383a0 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20 50 nterface saves P
383b0 20 61 73 20 6d 65 74 61 64 61 74 61 20 66 6f 72 as metadata for
383c0 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 the N-th.** arg
383d0 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 ument of the app
383e0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
383f0 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 53 75 62 function. ^Sub
38400 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 sequent.** calls
38410 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f to sqlite3_get_
38420 61 75 78 64 61 74 61 28 43 2c 4e 29 20 72 65 74 auxdata(C,N) ret
38430 75 72 6e 20 50 20 66 72 6f 6d 20 74 68 65 20 6d urn P from the m
38440 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 71 ost recent.** sq
38450 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 lite3_set_auxdat
38460 61 28 43 2c 4e 2c 50 2c 58 29 20 63 61 6c 6c 20 a(C,N,P,X) call
38470 69 66 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 if the metadata
38480 69 73 20 73 74 69 6c 6c 20 76 61 6c 69 64 20 6f is still valid o
38490 72 0a 2a 2a 20 4e 55 4c 4c 20 69 66 20 74 68 65 r.** NULL if the
384a0 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65 metadata has be
384b0 65 6e 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a en discarded..**
384c0 20 5e 41 66 74 65 72 20 65 61 63 68 20 63 61 6c ^After each cal
384d0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 l to sqlite3_set
384e0 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 _auxdata(C,N,P,X
384f0 29 20 77 68 65 72 65 20 58 20 69 73 20 6e 6f 74 ) where X is not
38500 20 4e 55 4c 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65 NULL,.** SQLite
38510 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 will invoke the
38520 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 destructor func
38530 74 69 6f 6e 20 58 20 77 69 74 68 20 70 61 72 61 tion X with para
38540 6d 65 74 65 72 20 50 20 65 78 61 63 74 6c 79 0a meter P exactly.
38550 2a 2a 20 6f 6e 63 65 2c 20 77 68 65 6e 20 74 68 ** once, when th
38560 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 69 e metadata is di
38570 73 63 61 72 64 65 64 2e 0a 2a 2a 20 53 51 4c 69 scarded..** SQLi
38580 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 64 69 te is free to di
38590 73 63 61 72 64 20 74 68 65 20 6d 65 74 61 64 61 scard the metada
385a0 74 61 20 61 74 20 61 6e 79 20 74 69 6d 65 2c 20 ta at any time,
385b0 69 6e 63 6c 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a including: <ul>.
385c0 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 74 68 65 ** <li> when the
385d0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 corresponding f
385e0 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 unction paramete
385f0 72 20 63 68 61 6e 67 65 73 2c 20 6f 72 0a 2a 2a r changes, or.**
38600 20 3c 6c 69 3e 20 77 68 65 6e 20 5b 73 71 6c 69 <li> when [sqli
38610 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 te3_reset()] or
38620 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
38630 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 66 e()] is called f
38640 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 53 or the.** S
38650 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 6f 72 QL statement, or
38660 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 73 71 .** <li> when sq
38670 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 lite3_set_auxdat
38680 61 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 a() is invoked a
38690 67 61 69 6e 20 6f 6e 20 74 68 65 20 73 61 6d 65 gain on the same
386a0 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 0a 2a parameter, or.*
386b0 2a 20 3c 6c 69 3e 20 64 75 72 69 6e 67 20 74 68 * <li> during th
386c0 65 20 6f 72 69 67 69 6e 61 6c 20 73 71 6c 69 74 e original sqlit
386d0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 e3_set_auxdata()
386e0 20 63 61 6c 6c 20 77 68 65 6e 20 61 20 6d 65 6d call when a mem
386f0 6f 72 79 20 0a 2a 2a 20 20 20 20 20 20 61 6c 6c ory .** all
38700 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 ocation error oc
38710 63 75 72 73 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a curs. </ul>)^.**
38720 0a 2a 2a 20 4e 6f 74 65 20 74 68 65 20 6c 61 73 .** Note the las
38730 74 20 62 75 6c 6c 65 74 20 69 6e 20 70 61 72 74 t bullet in part
38740 69 63 75 6c 61 72 2e 20 20 54 68 65 20 64 65 73 icular. The des
38750 74 72 75 63 74 6f 72 20 58 20 69 6e 20 0a 2a 2a tructor X in .**
38760 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 sqlite3_set_aux
38770 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 6d 69 data(C,N,P,X) mi
38780 6