0000: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a /***************
0010: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0020: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0030: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0040: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a ***************.
0050: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 69 73 20 ** This file is
0060: 61 6e 20 61 6d 61 6c 67 61 6d 61 74 69 6f 6e 20 an amalgamation
0070: 6f 66 20 6d 61 6e 79 20 73 65 70 61 72 61 74 65 of many separate
0080: 20 43 20 73 6f 75 72 63 65 20 66 69 6c 65 73 20 C source files
0090: 66 72 6f 6d 20 53 51 4c 69 74 65 0a 2a 2a 20 76 from SQLite.** v
00a0: 65 72 73 69 6f 6e 20 33 2e 31 30 2e 30 2e 20 20 ersion 3.10.0.
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 31 30 2e 30 22 0a 23 64 "3.10.0".#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 31 30 SION_NUMBER 3010
3130: 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 000.#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 31 32 2d 30 34 20 31 33 "2015-12-04 13
3160: 3a 34 34 3a 30 37 20 34 65 63 62 63 37 35 62 34 :44:07 4ecbc75b4
3170: 36 35 35 33 33 63 66 38 30 65 31 36 36 61 39 64 65533cf80e166a9d
3180: 30 38 37 39 62 39 61 66 64 33 66 65 32 62 65 22 0879b9afd3fe2be"
3190: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
31a0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 : Run-Time Libra
31b0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 ry Version Numbe
31c0: 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 rs.** KEYWORDS:
31d0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 2c sqlite3_version,
31e0: 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 sqlite3_sourcei
31f0: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e d.**.** These in
3200: 74 65 72 66 61 63 65 73 20 70 72 6f 76 69 64 65 terfaces provide
3210: 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d the same inform
3220: 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 ation as the [SQ
3230: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a LITE_VERSION],.*
3240: 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f * [SQLITE_VERSIO
3250: 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b N_NUMBER], and [
3260: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 SQLITE_SOURCE_ID
3270: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 ] C preprocessor
3280: 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61 macros.** but a
3290: 72 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 re associated wi
32a0: 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 20 69 th the library i
32b0: 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 68 65 nstead of the he
32c0: 61 64 65 72 20 66 69 6c 65 2e 20 20 5e 28 43 61 ader file. ^(Ca
32d0: 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61 utious.** progra
32e0: 6d 6d 65 72 73 20 6d 69 67 68 74 20 69 6e 63 6c mmers might incl
32f0: 75 64 65 20 61 73 73 65 72 74 28 29 20 73 74 61 ude assert() sta
3300: 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 69 72 tements in their
3310: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a application to.
3320: 2a 2a 20 76 65 72 69 66 79 20 74 68 61 74 20 76 ** verify that v
3330: 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 alues returned b
3340: 79 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 y these interfac
3350: 65 73 20 6d 61 74 63 68 20 74 68 65 20 6d 61 63 es match the mac
3360: 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65 ros in.** the he
3370: 61 64 65 72 2c 20 61 6e 64 20 74 68 75 73 20 65 ader, and thus e
3380: 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 61 nsure that the a
3390: 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a pplication is.**
33a0: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d compiled with m
33b0: 61 74 63 68 69 6e 67 20 6c 69 62 72 61 72 79 20 atching library
33c0: 61 6e 64 20 68 65 61 64 65 72 20 66 69 6c 65 73 and header files
33d0: 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 ..**.** <blockqu
33e0: 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 ote><pre>.** ass
33f0: 65 72 74 28 20 73 71 6c 69 74 65 33 5f 6c 69 62 ert( sqlite3_lib
3400: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 version_number()
3410: 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e ==SQLITE_VERSION
3420: 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73 _NUMBER );.** as
3430: 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c sert( strcmp(sql
3440: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 2c ite3_sourceid(),
3450: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 SQLITE_SOURCE_ID
3460: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 )==0 );.** asser
3470: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 t( strcmp(sqlite
3480: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53 3_libversion(),S
3490: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d QLITE_VERSION)==
34a0: 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 0 );.** </pre></
34b0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a blockquote>)^.**
34c0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
34d0: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e _version[] strin
34e0: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 g constant conta
34f0: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 ins the text of
3500: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d [SQLITE_VERSION]
3510: 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65 .** macro. ^The
3520: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 sqlite3_libvers
3530: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 ion() function r
3540: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
3550: 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68 to the.** to th
3560: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f e sqlite3_versio
3570: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 n[] string const
3580: 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 ant. The sqlite
3590: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a 3_libversion().*
35a0: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 * function is pr
35b0: 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69 ovided for use i
35c0: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c n DLLs since DLL
35d0: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64 users usually d
35e0: 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69 o not have.** di
35f0: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73 rect access to s
3600: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 tring constants
3610: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20 within the DLL.
3620: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 ^The.** sqlite3
3630: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 _libversion_numb
3640: 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 er() function re
3650: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 turns an integer
3660: 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 equal to.** [SQ
3670: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d LITE_VERSION_NUM
3680: 42 45 52 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 BER]. ^The sqli
3690: 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20 66 te3_sourceid() f
36a0: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
36b0: 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f .** a pointer to
36c0: 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 a string consta
36d0: 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20 69 nt whose value i
36e0: 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74 68 s the same as th
36f0: 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f e .** [SQLITE_SO
3700: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 URCE_ID] C prepr
3710: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a ocessor macro..*
3720: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
3730: 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 sqlite_version()
3740: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f ] and [sqlite_so
3750: 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53 urce_id()]..*/.S
3760: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
3770: 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 char sqlite3_ver
3780: 73 69 6f 6e 5b 5d 20 3d 20 53 51 4c 49 54 45 5f sion[] = SQLITE_
3790: 56 45 52 53 49 4f 4e 3b 0a 53 51 4c 49 54 45 5f VERSION;.SQLITE_
37a0: 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a API const char *
37b0: 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
37c0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f qlite3_libversio
37d0: 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f n(void);.SQLITE_
37e0: 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a API const char *
37f0: 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
3800: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 qlite3_sourceid(
3810: 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 void);.SQLITE_AP
3820: 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
3830: 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6c 69 62 CALL sqlite3_lib
3840: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 version_number(v
3850: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 oid);../*.** CAP
3860: 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 I3REF: Run-Time
3870: 4c 69 62 72 61 72 79 20 43 6f 6d 70 69 6c 61 74 Library Compilat
3880: 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69 61 67 ion Options Diag
3890: 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 nostics.**.** ^T
38a0: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 he sqlite3_compi
38b0: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 20 leoption_used()
38c0: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
38d0: 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69 0 or 1 .** indi
38e0: 63 61 74 69 6e 67 20 77 68 65 74 68 65 72 20 74 cating whether t
38f0: 68 65 20 73 70 65 63 69 66 69 65 64 20 6f 70 74 he specified opt
3900: 69 6f 6e 20 77 61 73 20 64 65 66 69 6e 65 64 20 ion was defined
3910: 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 at .** compile t
3920: 69 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 ime. ^The SQLIT
3930: 45 5f 20 70 72 65 66 69 78 20 6d 61 79 20 62 65 E_ prefix may be
3940: 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 omitted from th
3950: 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d e .** option nam
3960: 65 20 70 61 73 73 65 64 20 74 6f 20 73 71 6c 69 e passed to sqli
3970: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f te3_compileoptio
3980: 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a n_used(). .**.*
3990: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 * ^The sqlite3_c
39a0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 ompileoption_get
39b0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f () function allo
39c0: 77 73 20 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20 ws iterating.**
39d0: 6f 76 65 72 20 74 68 65 20 6c 69 73 74 20 6f 66 over the list of
39e0: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 77 65 options that we
39f0: 72 65 20 64 65 66 69 6e 65 64 20 61 74 20 63 6f re defined at co
3a00: 6d 70 69 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a mpile time by.**
3a10: 20 72 65 74 75 72 6e 69 6e 67 20 74 68 65 20 4e returning the N
3a20: 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 -th compile time
3a30: 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20 option string.
3a40: 20 5e 49 66 20 4e 20 69 73 20 6f 75 74 20 6f 66 ^If N is out of
3a50: 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74 range,.** sqlit
3a60: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e e3_compileoption
3a70: 5f 67 65 74 28 29 20 72 65 74 75 72 6e 73 20 61 _get() returns a
3a80: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 NULL pointer.
3a90: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a ^The SQLITE_ .**
3aa0: 20 70 72 65 66 69 78 20 69 73 20 6f 6d 69 74 74 prefix is omitt
3ab0: 65 64 20 66 72 6f 6d 20 61 6e 79 20 73 74 72 69 ed from any stri
3ac0: 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 ngs returned by
3ad0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 .** sqlite3_comp
3ae0: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e ileoption_get().
3af0: 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20 .**.** ^Support
3b00: 66 6f 72 20 74 68 65 20 64 69 61 67 6e 6f 73 74 for the diagnost
3b10: 69 63 20 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c ic functions sql
3b20: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 ite3_compileopti
3b30: 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64 on_used().** and
3b40: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 sqlite3_compile
3b50: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79 option_get() may
3b60: 20 62 65 20 6f 6d 69 74 74 65 64 20 62 79 20 73 be omitted by s
3b70: 70 65 63 69 66 79 69 6e 67 20 74 68 65 20 0a 2a pecifying the .*
3b80: 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 * [SQLITE_OMIT_C
3b90: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 OMPILEOPTION_DIA
3ba0: 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f GS] option at co
3bb0: 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a mpile time..**.*
3bc0: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20 * See also: SQL
3bd0: 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74 functions [sqlit
3be0: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f e_compileoption_
3bf0: 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b used()] and.** [
3c00: 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 sqlite_compileop
3c10: 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20 tion_get()] and
3c20: 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74 the [compile_opt
3c30: 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f ions pragma]..*/
3c40: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f .#ifndef SQLITE_
3c50: 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 OMIT_COMPILEOPTI
3c60: 4f 4e 5f 44 49 41 47 53 0a 53 51 4c 49 54 45 5f ON_DIAGS.SQLITE_
3c70: 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 API int SQLITE_S
3c80: 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 TDCALL sqlite3_c
3c90: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 ompileoption_use
3ca0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f d(const char *zO
3cb0: 70 74 4e 61 6d 65 29 3b 0a 53 51 4c 49 54 45 5f ptName);.SQLITE_
3cc0: 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a API const char *
3cd0: 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
3ce0: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 qlite3_compileop
3cf0: 74 69 6f 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b tion_get(int N);
3d00: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 .#endif../*.** C
3d10: 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f API3REF: Test To
3d20: 20 53 65 65 20 49 66 20 54 68 65 20 4c 69 62 72 See If The Libr
3d30: 61 72 79 20 49 73 20 54 68 72 65 61 64 73 61 66 ary Is Threadsaf
3d40: 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c e.**.** ^The sql
3d50: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 ite3_threadsafe(
3d60: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 ) function retur
3d70: 6e 73 20 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f ns zero if and o
3d80: 6e 6c 79 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 nly if.** SQLite
3d90: 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 was compiled wi
3da0: 74 68 20 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 th mutexing code
3db0: 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74 6f 20 omitted due to
3dc0: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 the.** [SQLITE_T
3dd0: 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 HREADSAFE] compi
3de0: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 le-time option b
3df0: 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a eing set to 0..*
3e00: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 *.** SQLite can
3e10: 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 be compiled with
3e20: 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65 or without mute
3e30: 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 xes. When.** th
3e40: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 e [SQLITE_THREAD
3e50: 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65 SAFE] C preproce
3e60: 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 31 20 ssor macro is 1
3e70: 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a or 2, mutexes.**
3e80: 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 are enabled and
3e90: 20 53 51 4c 69 74 65 20 69 73 20 74 68 72 65 61 SQLite is threa
3ea0: 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74 68 65 dsafe. When the
3eb0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 .** [SQLITE_THRE
3ec0: 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 ADSAFE] macro is
3ed0: 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 0, .** the mute
3ee0: 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65 64 2e xes are omitted.
3ef0: 20 20 57 69 74 68 6f 75 74 20 74 68 65 20 6d 75 Without the mu
3f00: 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 texes, it is not
3f10: 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 safe.** to use
3f20: 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72 65 6e SQLite concurren
3f30: 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 tly from more th
3f40: 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a an one thread..*
3f50: 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 *.** Enabling mu
3f60: 74 65 78 65 73 20 69 6e 63 75 72 73 20 61 20 6d texes incurs a m
3f70: 65 61 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72 easurable perfor
3f80: 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a mance penalty..*
3f90: 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20 69 73 * So if speed is
3fa0: 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 of utmost impor
3fb0: 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 tance, it makes
3fc0: 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62 6c 65 sense to disable
3fd0: 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 2e .** the mutexes.
3fe0: 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 But for maximu
3ff0: 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65 78 65 m safety, mutexe
4000: 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 s should be enab
4010: 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 led..** ^The def
4020: 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 73 ault behavior is
4030: 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74 6f 20 for mutexes to
4040: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a be enabled..**.*
4050: 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 * This interface
4060: 20 63 61 6e 20 62 65 20 75 73 65 64 20 62 79 20 can be used by
4070: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 an application t
4080: 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 o make sure that
4090: 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 the.** version
40a0: 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 of SQLite that i
40b0: 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 t is linking aga
40c0: 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 inst was compile
40d0: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 d with.** the de
40e0: 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66 sired setting of
40f0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
4100: 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a EADSAFE] macro..
4110: 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 **.** This inter
4120: 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 face only report
4130: 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 s on the compile
4140: 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65 74 74 -time mutex sett
4150: 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 ing.** of the [S
4160: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
4170: 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 ] flag. If SQLi
4180: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
4190: 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 ith.** SQLITE_TH
41a0: 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 READSAFE=1 or =2
41b0: 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72 then mutexes ar
41c0: 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 e enabled by def
41d0: 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 ault but.** can
41e0: 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 be fully or part
41f0: 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75 ially disabled u
4200: 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b sing a call to [
4210: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
4220: 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65 ].** with the ve
4230: 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 rbs [SQLITE_CONF
4240: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d IG_SINGLETHREAD]
4250: 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 , [SQLITE_CONFIG
4260: 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a _MULTITHREAD],.*
4270: 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e * or [SQLITE_CON
4280: 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e FIG_SERIALIZED].
4290: 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e 20 76 ^(The return v
42a0: 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 alue of the.** s
42b0: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 qlite3_threadsaf
42c0: 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f e() function sho
42d0: 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 ws only the comp
42e0: 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 ile-time setting
42f0: 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 of.** thread sa
4300: 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 fety, not any ru
4310: 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73 20 74 n-time changes t
4320: 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 6d o that setting m
4330: 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 ade by.** sqlite
4340: 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 3_config(). In o
4350: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 ther words, the
4360: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f return value fro
4370: 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 m sqlite3_thread
4380: 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 safe().** is unc
4390: 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c 73 20 hanged by calls
43a0: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 to sqlite3_confi
43b0: 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 g().)^.**.** See
43c0: 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 the [threading
43d0: 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 mode] documentat
43e0: 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e ion for addition
43f0: 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a al information..
4400: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
4410: 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
4420: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 sqlite3_threads
4430: 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a afe(void);../*.*
4440: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 * CAPI3REF: Data
4450: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 base Connection
4460: 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 Handle.** KEYWOR
4470: 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f DS: {database co
4480: 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 nnection} {datab
4490: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d ase connections}
44a0: 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e .**.** Each open
44b0: 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 SQLite database
44c0: 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 is represented
44d0: 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 by a pointer to
44e0: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a an instance of.*
44f0: 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73 74 72 * the opaque str
4500: 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73 71 ucture named "sq
4510: 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73 20 75 lite3". It is u
4520: 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f seful to think o
4530: 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 f an sqlite3.**
4540: 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 pointer as an ob
4550: 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 ject. The [sqli
4560: 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 te3_open()], [sq
4570: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c lite3_open16()],
4580: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and.** [sqlite3
4590: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 _open_v2()] inte
45a0: 72 66 61 63 65 73 20 61 72 65 20 69 74 73 20 63 rfaces are its c
45b0: 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 onstructors, and
45c0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 [sqlite3_close(
45d0: 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 )].** and [sqlit
45e0: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 5d 20 61 e3_close_v2()] a
45f0: 72 65 20 69 74 73 20 64 65 73 74 72 75 63 74 6f re its destructo
4600: 72 73 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d rs. There are m
4610: 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 any other.** int
4620: 65 72 66 61 63 65 73 20 28 73 75 63 68 20 61 73 erfaces (such as
4630: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
4640: 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c pare_v2()], [sql
4650: 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
4660: 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 tion()], and.**
4670: 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 [sqlite3_busy_ti
4680: 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 meout()] to name
4690: 20 62 75 74 20 74 68 72 65 65 29 20 74 68 61 74 but three) that
46a0: 20 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 are methods on
46b0: 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 an.** sqlite3 ob
46c0: 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 ject..*/.typedef
46d0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20 struct sqlite3
46e0: 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 sqlite3;../*.**
46f0: 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74 CAPI3REF: 64-Bit
4700: 20 49 6e 74 65 67 65 72 20 54 79 70 65 73 0a 2a Integer Types.*
4710: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 * KEYWORDS: sqli
4720: 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f te_int64 sqlite_
4730: 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 uint64.**.** Bec
4740: 61 75 73 65 20 74 68 65 72 65 20 69 73 20 6e 6f ause there is no
4750: 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 cross-platform
4760: 77 61 79 20 74 6f 20 73 70 65 63 69 66 79 20 36 way to specify 6
4770: 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 74 79 4-bit integer ty
4780: 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e pes.** SQLite in
4790: 63 6c 75 64 65 73 20 74 79 70 65 64 65 66 73 20 cludes typedefs
47a0: 66 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 for 64-bit signe
47b0: 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 d and unsigned i
47c0: 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 ntegers..**.** T
47d0: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 he sqlite3_int64
47e0: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 6e and sqlite3_uin
47f0: 74 36 34 20 61 72 65 20 74 68 65 20 70 72 65 66 t64 are the pref
4800: 65 72 72 65 64 20 74 79 70 65 20 64 65 66 69 6e erred type defin
4810: 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 itions..** The s
4820: 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 qlite_int64 and
4830: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 sqlite_uint64 ty
4840: 70 65 73 20 61 72 65 20 73 75 70 70 6f 72 74 65 pes are supporte
4850: 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a d for backwards.
4860: 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 ** compatibility
4870: 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 only..**.** ^Th
4880: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 e sqlite3_int64
4890: 61 6e 64 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 and sqlite_int64
48a0: 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65 types can store
48b0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 0a integer values.
48c0: 2a 2a 20 62 65 74 77 65 65 6e 20 2d 39 32 32 33 ** between -9223
48d0: 33 37 32 30 33 36 38 35 34 37 37 35 38 30 38 20 372036854775808
48e0: 61 6e 64 20 2b 39 32 32 33 33 37 32 30 33 36 38 and +92233720368
48f0: 35 34 37 37 35 38 30 37 20 69 6e 63 6c 75 73 69 54775807 inclusi
4900: 76 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c ve. ^The.** sql
4910: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 6e 64 20 ite3_uint64 and
4920: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 sqlite_uint64 ty
4930: 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e pes can store in
4940: 74 65 67 65 72 20 76 61 6c 75 65 73 20 0a 2a 2a teger values .**
4950: 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 2b between 0 and +
4960: 31 38 34 34 36 37 34 34 30 37 33 37 30 39 35 35 1844674407370955
4970: 31 36 31 35 20 69 6e 63 6c 75 73 69 76 65 2e 0a 1615 inclusive..
4980: 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 */.#ifdef SQLITE
4990: 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 74 79 _INT64_TYPE. ty
49a0: 70 65 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 pedef SQLITE_INT
49b0: 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 69 64_TYPE sqlite_i
49c0: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 nt64;. typedef
49d0: 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f unsigned SQLITE_
49e0: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 INT64_TYPE sqlit
49f0: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 e_uint64;.#elif
4a00: 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 defined(_MSC_VER
4a10: 29 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 ) || defined(__B
4a20: 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 ORLANDC__). typ
4a30: 65 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c edef __int64 sql
4a40: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 ite_int64;. typ
4a50: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f edef unsigned __
4a60: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e int64 sqlite_uin
4a70: 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 t64;.#else. typ
4a80: 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 edef long long i
4a90: 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b nt sqlite_int64;
4aa0: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 . typedef unsig
4ab0: 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e ned long long in
4ac0: 74 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b t sqlite_uint64;
4ad0: 0a 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 .#endif.typedef
4ae0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c sqlite_int64 sql
4af0: 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 ite3_int64;.type
4b00: 64 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 def sqlite_uint6
4b10: 34 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 4 sqlite3_uint64
4b20: 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 ;../*.** If comp
4b30: 69 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 iling for a proc
4b40: 65 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 essor that lacks
4b50: 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 floating point
4b60: 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 support,.** subs
4b70: 74 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 titute integer f
4b80: 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e or floating-poin
4b90: 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c t..*/.#ifdef SQL
4ba0: 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e ITE_OMIT_FLOATIN
4bb0: 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 G_POINT.# define
4bc0: 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f double sqlite3_
4bd0: 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a int64.#endif../*
4be0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c .** CAPI3REF: Cl
4bf0: 6f 73 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 osing A Database
4c00: 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 44 Connection.** D
4c10: 45 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 ESTRUCTOR: sqlit
4c20: 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 e3.**.** ^The sq
4c30: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e lite3_close() an
4c40: 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f d sqlite3_close_
4c50: 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 v2() routines ar
4c60: 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a e destructors.**
4c70: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 for the [sqlite
4c80: 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 3] object..** ^C
4c90: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f alls to sqlite3_
4ca0: 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 close() and sqli
4cb0: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 te3_close_v2() r
4cc0: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b eturn [SQLITE_OK
4cd0: 5d 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c ] if.** the [sql
4ce0: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 ite3] object is
4cf0: 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 successfully des
4d00: 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 troyed and all a
4d10: 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 ssociated.** res
4d20: 6f 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c ources are deall
4d30: 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 ocated..**.** ^I
4d40: 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 f the database c
4d50: 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 onnection is ass
4d60: 6f 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 ociated with unf
4d70: 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 inalized prepare
4d80: 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 d.** statements
4d90: 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 or unfinished sq
4da0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a lite3_backup obj
4db0: 65 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 ects then sqlite
4dc0: 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 3_close().** wil
4dd0: 6c 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 l leave the data
4de0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
4df0: 6f 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 open and return
4e00: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a [SQLITE_BUSY]..*
4e10: 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c * ^If sqlite3_cl
4e20: 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c ose_v2() is call
4e30: 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 ed with unfinali
4e40: 7a 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 zed prepared sta
4e50: 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f 6f tements.** and/o
4e60: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c r unfinished sql
4e70: 69 74 65 33 5f 62 61 63 6b 75 70 73 2c 20 74 68 ite3_backups, th
4e80: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
4e90: 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 63 6f 6d connection becom
4ea0: 65 73 0a 2a 2a 20 61 6e 20 75 6e 75 73 61 62 6c es.** an unusabl
4eb0: 65 20 22 7a 6f 6d 62 69 65 22 20 77 68 69 63 68 e "zombie" which
4ec0: 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 will automatica
4ed0: 6c 6c 79 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 lly be deallocat
4ee0: 65 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c ed when the.** l
4ef0: 61 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 ast prepared sta
4f00: 74 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 tement is finali
4f10: 7a 65 64 20 6f 72 20 74 68 65 20 6c 61 73 74 20 zed or the last
4f20: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 69 sqlite3_backup i
4f30: 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 2e 20 20 s.** finished.
4f40: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 The sqlite3_clos
4f50: 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 e_v2() interface
4f60: 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 is intended for
4f70: 20 75 73 65 20 77 69 74 68 0a 2a 2a 20 68 6f 73 use with.** hos
4f80: 74 20 6c 61 6e 67 75 61 67 65 73 20 74 68 61 74 t languages that
4f90: 20 61 72 65 20 67 61 72 62 61 67 65 20 63 6f 6c are garbage col
4fa0: 6c 65 63 74 65 64 2c 20 61 6e 64 20 77 68 65 72 lected, and wher
4fb0: 65 20 74 68 65 20 6f 72 64 65 72 20 69 6e 20 77 e the order in w
4fc0: 68 69 63 68 0a 2a 2a 20 64 65 73 74 72 75 63 74 hich.** destruct
4fd0: 6f 72 73 20 61 72 65 20 63 61 6c 6c 65 64 20 69 ors are called i
4fe0: 73 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a s arbitrary..**.
4ff0: 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 ** Applications
5000: 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f should [sqlite3_
5010: 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c finalize | final
5020: 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 ize] all [prepar
5030: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 0a ed statements],.
5040: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 ** [sqlite3_blob
5050: 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 _close | close]
5060: 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 all [BLOB handle
5070: 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c s], and .** [sql
5080: 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 ite3_backup_fini
5090: 73 68 20 7c 20 66 69 6e 69 73 68 5d 20 61 6c 6c sh | finish] all
50a0: 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 [sqlite3_backup
50b0: 5d 20 6f 62 6a 65 63 74 73 20 61 73 73 6f 63 69 ] objects associ
50c0: 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 ated.** with the
50d0: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 [sqlite3] objec
50e0: 74 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d t prior to attem
50f0: 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 pting to close t
5100: 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a he object. ^If.
5110: 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 ** sqlite3_close
5120: 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 _v2() is called
5130: 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 on a [database c
5140: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 onnection] that
5150: 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 still has.** out
5160: 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 standing [prepar
5170: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 ed statements],
5180: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 [BLOB handles],
5190: 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 and/or.** [sqlit
51a0: 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 e3_backup] objec
51b0: 74 73 20 74 68 65 6e 20 69 74 20 72 65 74 75 72 ts then it retur
51c0: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 61 ns [SQLITE_OK] a
51d0: 6e 64 20 74 68 65 20 64 65 61 6c 6c 6f 63 61 74 nd the deallocat
51e0: 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f 75 72 ion.** of resour
51f0: 63 65 73 20 69 73 20 64 65 66 65 72 72 65 64 20 ces is deferred
5200: 75 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65 70 61 until all [prepa
5210: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c red statements],
5220: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c [BLOB handles],
5230: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 .** and [sqlite3
5240: 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 _backup] objects
5250: 20 61 72 65 20 61 6c 73 6f 20 64 65 73 74 72 6f are also destro
5260: 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 yed..**.** ^If a
5270: 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 n [sqlite3] obje
5280: 63 74 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 ct is destroyed
5290: 77 68 69 6c 65 20 61 20 74 72 61 6e 73 61 63 74 while a transact
52a0: 69 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 ion is open,.**
52b0: 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 the transaction
52c0: 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 is automatically
52d0: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a rolled back..**
52e0: 0a 2a 2a 20 54 68 65 20 43 20 70 61 72 61 6d 65 .** The C parame
52f0: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ter to [sqlite3_
5300: 63 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20 5b 73 close(C)] and [s
5310: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 qlite3_close_v2(
5320: 43 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 C)].** must be e
5330: 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 ither a NULL.**
5340: 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 pointer or an [s
5350: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 qlite3] object p
5360: 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 0a ointer obtained.
5370: 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ** from [sqlite3
5380: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 _open()], [sqlit
5390: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 e3_open16()], or
53a0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 .** [sqlite3_ope
53b0: 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 n_v2()], and not
53c0: 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 previously clos
53d0: 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 ed..** ^Calling
53e0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 sqlite3_close()
53f0: 6f 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 or sqlite3_close
5400: 5f 76 32 28 29 20 77 69 74 68 20 61 20 4e 55 4c _v2() with a NUL
5410: 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 72 67 L pointer.** arg
5420: 75 6d 65 6e 74 20 69 73 20 61 20 68 61 72 6d 6c ument is a harml
5430: 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 ess no-op..*/.SQ
5440: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
5450: 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
5460: 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 te3_close(sqlite
5470: 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 3*);.SQLITE_API
5480: 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 int SQLITE_STDCA
5490: 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 LL sqlite3_close
54a0: 5f 76 32 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a _v2(sqlite3*);..
54b0: 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 /*.** The type f
54c0: 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 or a callback fu
54d0: 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 nction..** This
54e0: 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 is legacy and de
54f0: 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 precated. It is
5500: 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 included for hi
5510: 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 storical.** comp
5520: 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 atibility and is
5530: 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e not documented.
5540: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 .*/.typedef int
5550: 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 (*sqlite3_callba
5560: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 ck)(void*,int,ch
5570: 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a ar**, char**);..
5580: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
5590: 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 One-Step Query E
55a0: 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 xecution Interfa
55b0: 63 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 ce.** METHOD: sq
55c0: 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 lite3.**.** The
55d0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 sqlite3_exec() i
55e0: 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f nterface is a co
55f0: 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65 nvenience wrappe
5600: 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c r around.** [sql
5610: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
5620: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 )], [sqlite3_ste
5630: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 p()], and [sqlit
5640: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a e3_finalize()],.
5650: 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61 ** that allows a
5660: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f n application to
5670: 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74 run multiple st
5680: 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a atements of SQL.
5690: 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e ** without havin
56a0: 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f g to use a lot o
56b0: 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a f C code. .**.**
56c0: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 ^The sqlite3_ex
56d0: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 ec() interface r
56e0: 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 uns zero or more
56f0: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a UTF-8 encoded,.
5700: 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 ** semicolon-sep
5710: 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d arate SQL statem
5720: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f ents passed into
5730: 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e its 2nd argumen
5740: 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e t,.** in the con
5750: 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74 text of the [dat
5760: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
5770: 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 69 ] passed in as i
5780: 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65 ts 1st.** argume
5790: 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c nt. ^If the cal
57a0: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f lback function o
57b0: 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65 f the 3rd argume
57c0: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 nt to.** sqlite3
57d0: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e _exec() is not N
57e0: 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20 ULL, then it is
57f0: 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68 invoked for each
5800: 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 result row.** c
5810: 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65 oming out of the
5820: 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73 evaluated SQL s
5830: 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65 tatements. ^The
5840: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 4th argument to
5850: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 .** sqlite3_exec
5860: 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 () is relayed th
5870: 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 rough to the 1st
5880: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 argument of eac
5890: 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e h.** callback in
58a0: 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 vocation. ^If t
58b0: 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e he callback poin
58c0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 ter to sqlite3_e
58d0: 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c xec().** is NULL
58e0: 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 , then no callba
58f0: 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b ck is ever invok
5900: 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f ed and result ro
5910: 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 ws are.** ignore
5920: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 d..**.** ^If an
5930: 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 error occurs whi
5940: 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 le evaluating th
5950: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 e SQL statements
5960: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 passed into.**
5970: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 sqlite3_exec(),
5980: 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f then execution o
5990: 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 f the current st
59a0: 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e atement stops an
59b0: 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 d.** subsequent
59c0: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 statements are s
59d0: 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 kipped. ^If the
59e0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 5th parameter t
59f0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 o sqlite3_exec()
5a00: 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 .** is not NULL
5a10: 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d then any error m
5a20: 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65 essage is writte
5a30: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 n into memory ob
5a40: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b tained.** from [
5a50: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
5a60: 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 ] and passed bac
5a70: 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 k through the 5t
5a80: 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 h parameter..**
5a90: 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 To avoid memory
5aa0: 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 leaks, the appli
5ab0: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e cation should in
5ac0: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 voke [sqlite3_fr
5ad0: 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f ee()].** on erro
5ae0: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 r message string
5af0: 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 s returned throu
5b00: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d gh the 5th param
5b10: 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 eter of.** of sq
5b20: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 lite3_exec() aft
5b30: 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 er the error mes
5b40: 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e sage string is n
5b50: 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e o longer needed.
5b60: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 .** ^If the 5th
5b70: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
5b80: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e ite3_exec() is n
5b90: 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 ot NULL and no e
5ba0: 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 rrors.** occur,
5bb0: 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 then sqlite3_exe
5bc0: 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 c() sets the poi
5bd0: 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 nter in its 5th
5be0: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 parameter to.**
5bf0: 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 NULL before retu
5c00: 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 rning..**.** ^If
5c10: 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 an sqlite3_exec
5c20: 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 () callback retu
5c30: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 rns non-zero, th
5c40: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 e sqlite3_exec()
5c50: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 .** routine retu
5c60: 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 rns SQLITE_ABORT
5c70: 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e without invokin
5c80: 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 g the callback a
5c90: 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 gain and.** with
5ca0: 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 out running any
5cb0: 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 subsequent SQL s
5cc0: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a tatements..**.**
5cd0: 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 ^The 2nd argume
5ce0: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 nt to the sqlite
5cf0: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 3_exec() callbac
5d00: 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 k function is th
5d10: 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 e.** number of c
5d20: 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 olumns in the re
5d30: 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 sult. ^The 3rd
5d40: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 argument to the
5d50: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a sqlite3_exec().*
5d60: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e * callback is an
5d70: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 array of pointe
5d80: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 rs to strings ob
5d90: 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f tained as if fro
5da0: 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f m.** [sqlite3_co
5db0: 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e lumn_text()], on
5dc0: 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d e for each colum
5dd0: 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 n. ^If an eleme
5de0: 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c nt of a.** resul
5df0: 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 t row is NULL th
5e00: 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e en the correspon
5e10: 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e ding string poin
5e20: 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 ter for the.** s
5e30: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 qlite3_exec() ca
5e40: 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c llback is a NULL
5e50: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 pointer. ^The
5e60: 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 4th argument to
5e70: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 the.** sqlite3_e
5e80: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 xec() callback i
5e90: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f s an array of po
5ea0: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 inters to string
5eb0: 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 s where each.**
5ec0: 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 entry represents
5ed0: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 the name of cor
5ee0: 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c responding resul
5ef0: 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 t column as obta
5f00: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 ined.** from [sq
5f10: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d lite3_column_nam
5f20: 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 e()]..**.** ^If
5f30: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 the 2nd paramete
5f40: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 r to sqlite3_exe
5f50: 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f c() is a NULL po
5f60: 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 inter, a pointer
5f70: 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 .** to an empty
5f80: 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 string, or a poi
5f90: 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 nter that contai
5fa0: 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 ns only whitespa
5fb0: 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 ce and/or .** SQ
5fc0: 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e L comments, then
5fd0: 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e no SQL statemen
5fe0: 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 ts are evaluated
5ff0: 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 and the databas
6000: 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e e.** is not chan
6010: 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 ged..**.** Restr
6020: 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c ictions:.**.** <
6030: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 ul>.** <li> The
6040: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 application must
6050: 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 ensure that the
6060: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 1st parameter t
6070: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 o sqlite3_exec()
6080: 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 .** is a va
6090: 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 lid and open [da
60a0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
60b0: 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 n]..** <li> The
60c0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 application must
60d0: 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 5b not close the [
60e0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
60f0: 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 ion] specified b
6100: 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73 y.** the 1s
6110: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 t parameter to s
6120: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 qlite3_exec() wh
6130: 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 ile sqlite3_exec
6140: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a () is running..*
6150: 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 * <li> The appli
6160: 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 cation must not
6170: 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 73 modify the SQL s
6180: 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61 tatement text pa
6190: 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 ssed into.**
61a0: 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 the 2nd parame
61b0: 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 ter of sqlite3_e
61c0: 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 xec() while sqli
61d0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 te3_exec() is ru
61e0: 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a nning..** </ul>.
61f0: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
6200: 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
6210: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 sqlite3_exec(.
6220: 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 sqlite3*,
6230: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
6240: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 /* A
6250: 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 n open database
6260: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
6270: 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 *sql,
6280: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
6290: 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 /* SQL to be eva
62a0: 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 luated */. int
62b0: 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 (*callback)(void
62c0: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 *,int,char**,cha
62d0: 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 r**), /* Callba
62e0: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 ck function */.
62f0: 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 void *,
6300: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
6310: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31 /* 1
6320: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 st argument to c
6330: 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 allback */. cha
6340: 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 r **errmsg
6350: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
6360: 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 /* Error
6370: 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 msg written her
6380: 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 e */.);../*.** C
6390: 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 API3REF: Result
63a0: 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 Codes.** KEYWORD
63b0: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 20 S: {result code
63c0: 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a definitions}.**.
63d0: 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 ** Many SQLite f
63e0: 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 unctions return
63f0: 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c an integer resul
6400: 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 t code from the
6410: 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 set shown.** her
6420: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e e in order to in
6430: 64 69 63 61 74 65 20 73 75 63 63 65 73 73 20 6f dicate success o
6440: 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a r failure..**.**
6450: 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 New error codes
6460: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e may be added in
6470: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 future versions
6480: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a of SQLite..**.*
6490: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74 * See also: [ext
64a0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
64b0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a e definitions].*
64c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
64d0: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 _OK 0
64e0: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 /* Successful
64f0: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 result */./* beg
6500: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d inning-of-error-
6510: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 codes */.#define
6520: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 SQLITE_ERROR
6530: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 1 /* SQL
6540: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 error or missing
6550: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 database */.#de
6560: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 fine SQLITE_INTE
6570: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 RNAL 2 /*
6580: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 Internal logic e
6590: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a rror in SQLite *
65a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
65b0: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20 _PERM 3
65c0: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d /* Access perm
65d0: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f ission denied */
65e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
65f0: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20 ABORT 4
6600: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 /* Callback rou
6610: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61 tine requested a
6620: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 n abort */.#defi
6630: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20 ne SQLITE_BUSY
6640: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68 5 /* Th
6650: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
6660: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 is locked */.#de
6670: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b fine SQLITE_LOCK
6680: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20 ED 6 /*
6690: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64 A table in the d
66a0: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 atabase is locke
66b0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
66c0: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 ITE_NOMEM
66d0: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 7 /* A malloc
66e0: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 () failed */.#de
66f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 fine SQLITE_READ
6700: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20 ONLY 8 /*
6710: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 Attempt to write
6720: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 a readonly data
6730: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 base */.#define
6740: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 SQLITE_INTERRUPT
6750: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 9 /* Opera
6760: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 tion terminated
6770: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 by sqlite3_inter
6780: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 rupt()*/.#define
6790: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 SQLITE_IOERR
67a0: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 10 /* Some
67b0: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f kind of disk I/
67c0: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64 O error occurred
67d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
67e0: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31 TE_CORRUPT 1
67f0: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 1 /* The datab
6800: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69 ase disk image i
6810: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 s malformed */.#
6820: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f define SQLITE_NO
6830: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f TFOUND 12 /
6840: 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 * Unknown opcode
6850: 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 in sqlite3_file
6860: 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 _control() */.#d
6870: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c efine SQLITE_FUL
6880: 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a L 13 /*
6890: 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 Insertion faile
68a0: 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61 d because databa
68b0: 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 se is full */.#d
68c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e efine SQLITE_CAN
68d0: 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a TOPEN 14 /*
68e0: 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 Unable to open
68f0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
6900: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c e */.#define SQL
6910: 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 ITE_PROTOCOL
6920: 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 15 /* Database
6930: 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 lock protocol e
6940: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 rror */.#define
6950: 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 SQLITE_EMPTY
6960: 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 16 /* Datab
6970: 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a ase is empty */.
6980: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
6990: 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 CHEMA 17
69a0: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 /* The database
69b0: 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a schema changed *
69c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
69d0: 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 _TOOBIG 18
69e0: 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 /* String or B
69f0: 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 LOB exceeds size
6a00: 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e limit */.#defin
6a10: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 e SQLITE_CONSTRA
6a20: 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f INT 19 /* Abo
6a30: 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 rt due to constr
6a40: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a aint violation *
6a50: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
6a60: 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 _MISMATCH 20
6a70: 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d /* Data type m
6a80: 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 ismatch */.#defi
6a90: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 ne SQLITE_MISUSE
6aa0: 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 21 /* Li
6ab0: 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 brary used incor
6ac0: 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e rectly */.#defin
6ad0: 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 e SQLITE_NOLFS
6ae0: 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 22 /* Use
6af0: 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f s OS features no
6b00: 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 t supported on h
6b10: 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ost */.#define S
6b20: 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 QLITE_AUTH
6b30: 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 23 /* Author
6b40: 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a ization denied *
6b50: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
6b60: 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 _FORMAT 24
6b70: 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 /* Auxiliary d
6b80: 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 atabase format e
6b90: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 rror */.#define
6ba0: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 SQLITE_RANGE
6bb0: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 25 /* 2nd p
6bc0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
6bd0: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 te3_bind out of
6be0: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 range */.#define
6bf0: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 SQLITE_NOTADB
6c00: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 26 /* File
6c10: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 opened that is
6c20: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66 not a database f
6c30: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ile */.#define S
6c40: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20 QLITE_NOTICE
6c50: 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69 27 /* Notifi
6c60: 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c cations from sql
6c70: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 ite3_log() */.#d
6c80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 efine SQLITE_WAR
6c90: 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a NING 28 /*
6ca0: 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73 Warnings from s
6cb0: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a qlite3_log() */.
6cc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
6cd0: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20 OW 100
6ce0: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 /* sqlite3_step(
6cf0: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f ) has another ro
6d00: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 w ready */.#defi
6d10: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 ne SQLITE_DONE
6d20: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 101 /* sq
6d30: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 lite3_step() has
6d40: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 finished execut
6d50: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 ing */./* end-of
6d60: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a -error-codes */.
6d70: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
6d80: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 Extended Result
6d90: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 Codes.** KEYWOR
6da0: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65 DS: {extended re
6db0: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 sult code defini
6dc0: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 tions}.**.** In
6dd0: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 its default conf
6de0: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 iguration, SQLit
6df0: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 e API routines r
6e00: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20 eturn one of 30
6e10: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75 integer.** [resu
6e20: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 lt codes]. Howe
6e30: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 ver, experience
6e40: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d has shown that m
6e50: 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 any of.** these
6e60: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 result codes are
6e70: 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 too coarse-grai
6e80: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f ned. They do no
6e90: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 t provide as.**
6ea0: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e much information
6eb0: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 about problems
6ec0: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d as programmers m
6ed0: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 ight like. In a
6ee0: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 n effort to.** a
6ef0: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 ddress this, new
6f00: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 er versions of S
6f10: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 QLite (version 3
6f20: 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20 .3.8 and later)
6f30: 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f include.** suppo
6f40: 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 rt for additiona
6f50: 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 l result codes t
6f60: 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 hat provide more
6f70: 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d detailed inform
6f80: 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 ation.** about e
6f90: 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b 65 78 rrors. These [ex
6fa0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
6fb0: 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64 des] are enabled
6fc0: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 or disabled.**
6fd0: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73 on a per databas
6fe0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 e connection bas
6ff0: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 is using the.**
7000: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 [sqlite3_extende
7010: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 d_result_codes()
7020: 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68 65 20 ] API. Or, the
7030: 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20 66 6f extended code fo
7040: 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65 r.** the most re
7050: 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e 20 62 cent error can b
7060: 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69 6e 67 e obtained using
7070: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 .** [sqlite3_ext
7080: 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d ended_errcode()]
7090: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
70a0: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 ITE_IOERR_READ
70b0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
70c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c ITE_IOERR | (1<<
70d0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
70e0: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 TE_IOERR_SHORT_R
70f0: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 EAD (SQLI
7100: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 TE_IOERR | (2<<8
7110: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
7120: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 E_IOERR_WRITE
7130: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
7140: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 E_IOERR | (3<<8)
7150: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
7160: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 _IOERR_FSYNC
7170: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
7180: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 _IOERR | (4<<8))
7190: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
71a0: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 IOERR_DIR_FSYNC
71b0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
71c0: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a IOERR | (5<<8)).
71d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
71e0: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 OERR_TRUNCATE
71f0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
7200: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 OERR | (6<<8)).#
7210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
7220: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 ERR_FSTAT
7230: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
7240: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 ERR | (7<<8)).#d
7250: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
7260: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 RR_UNLOCK
7270: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
7280: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 RR | (8<<8)).#de
7290: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
72a0: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 R_RDLOCK
72b0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
72c0: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 R | (9<<8)).#def
72d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
72e0: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 _DELETE
72f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
7300: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 | (10<<8)).#def
7310: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
7320: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 _BLOCKED
7330: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
7340: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 | (11<<8)).#def
7350: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
7360: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 _NOMEM
7370: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
7380: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 | (12<<8)).#def
7390: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
73a0: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20 _ACCESS
73b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
73c0: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 | (13<<8)).#def
73d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
73e0: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f _CHECKRESERVEDLO
73f0: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 CK (SQLITE_IOERR
7400: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 | (14<<8)).#def
7410: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
7420: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 _LOCK
7430: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
7440: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 | (15<<8)).#def
7450: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
7460: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20 _CLOSE
7470: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
7480: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 | (16<<8)).#def
7490: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
74a0: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 _DIR_CLOSE
74b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
74c0: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 | (17<<8)).#def
74d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
74e0: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 _SHMOPEN
74f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
7500: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 | (18<<8)).#def
7510: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
7520: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20 _SHMSIZE
7530: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
7540: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 | (19<<8)).#def
7550: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
7560: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 _SHMLOCK
7570: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
7580: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 | (20<<8)).#def
7590: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
75a0: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20 _SHMMAP
75b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
75c0: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 | (21<<8)).#def
75d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
75e0: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20 _SEEK
75f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
7600: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 | (22<<8)).#def
7610: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
7620: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 _DELETE_NOENT
7630: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
7640: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 | (23<<8)).#def
7650: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
7660: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 _MMAP
7670: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
7680: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 | (24<<8)).#def
7690: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
76a0: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20 _GETTEMPPATH
76b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
76c0: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 | (25<<8)).#def
76d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
76e0: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 _CONVPATH
76f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
7700: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 | (26<<8)).#def
7710: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
7720: 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20 _VNODE
7730: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
7740: 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66 | (27<<8)).#def
7750: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
7760: 5f 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20 _AUTH
7770: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
7780: 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66 | (28<<8)).#def
7790: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 ine SQLITE_LOCKE
77a0: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 D_SHAREDCACHE
77b0: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 (SQLITE_LOCKE
77c0: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 D | (1<<8)).#de
77d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 fine SQLITE_BUSY
77e0: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 _RECOVERY
77f0: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 (SQLITE_BUSY
7800: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 | (1<<8)).#d
7810: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 efine SQLITE_BUS
7820: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20 Y_SNAPSHOT
7830: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 (SQLITE_BUS
7840: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 Y | (2<<8)).#
7850: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 define SQLITE_CA
7860: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 NTOPEN_NOTEMPDIR
7870: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 (SQLITE_CA
7880: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 NTOPEN | (1<<8))
7890: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
78a0: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 CANTOPEN_ISDIR
78b0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
78c0: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 CANTOPEN | (2<<8
78d0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
78e0: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 E_CANTOPEN_FULLP
78f0: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 ATH (SQLIT
7900: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c E_CANTOPEN | (3<
7910: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
7920: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e ITE_CANTOPEN_CON
7930: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c VPATH (SQL
7940: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 ITE_CANTOPEN | (
7950: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 4<<8)).#define S
7960: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 QLITE_CORRUPT_VT
7970: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53 AB (S
7980: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 QLITE_CORRUPT |
7990: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (1<<8)).#define
79a0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f SQLITE_READONLY_
79b0: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28 RECOVERY (
79c0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 SQLITE_READONLY
79d0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (1<<8)).#defin
79e0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c e SQLITE_READONL
79f0: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 Y_CANTLOCK
7a00: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c (SQLITE_READONL
7a10: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 Y | (2<<8)).#def
7a20: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f ine SQLITE_READO
7a30: 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 NLY_ROLLBACK
7a40: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f (SQLITE_READO
7a50: 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 NLY | (3<<8)).#d
7a60: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 efine SQLITE_REA
7a70: 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20 DONLY_DBMOVED
7a80: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 (SQLITE_REA
7a90: 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a DONLY | (4<<8)).
7aa0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
7ab0: 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 BORT_ROLLBACK
7ac0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 (SQLITE_A
7ad0: 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 BORT | (2<<8)).#
7ae0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
7af0: 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 NSTRAINT_CHECK
7b00: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f (SQLITE_CO
7b10: 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 NSTRAINT | (1<<8
7b20: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
7b30: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d E_CONSTRAINT_COM
7b40: 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 MITHOOK (SQLIT
7b50: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 E_CONSTRAINT | (
7b60: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 2<<8)).#define S
7b70: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
7b80: 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53 _FOREIGNKEY (S
7b90: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
7ba0: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 | (3<<8)).#defi
7bb0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 ne SQLITE_CONSTR
7bc0: 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 AINT_FUNCTION
7bd0: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 (SQLITE_CONSTR
7be0: 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 AINT | (4<<8)).#
7bf0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
7c00: 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c NSTRAINT_NOTNULL
7c10: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f (SQLITE_CO
7c20: 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 NSTRAINT | (5<<8
7c30: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
7c40: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 E_CONSTRAINT_PRI
7c50: 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54 MARYKEY (SQLIT
7c60: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 E_CONSTRAINT | (
7c70: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 6<<8)).#define S
7c80: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
7c90: 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53 _TRIGGER (S
7ca0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
7cb0: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 | (7<<8)).#defi
7cc0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 ne SQLITE_CONSTR
7cd0: 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20 AINT_UNIQUE
7ce0: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 (SQLITE_CONSTR
7cf0: 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 AINT | (8<<8)).#
7d00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
7d10: 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20 NSTRAINT_VTAB
7d20: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f (SQLITE_CO
7d30: 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 NSTRAINT | (9<<8
7d40: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
7d50: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57 E_CONSTRAINT_ROW
7d60: 49 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 ID (SQLIT
7d70: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31 E_CONSTRAINT |(1
7d80: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 0<<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 57 41 4c 20 20 20 20 20 20 28 53 OVER_WAL (S
7db0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 QLITE_NOTICE | (
7dc0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 1<<8)).#define S
7dd0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 QLITE_NOTICE_REC
7de0: 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 OVER_ROLLBACK (S
7df0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 QLITE_NOTICE | (
7e00: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 2<<8)).#define S
7e10: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55 QLITE_WARNING_AU
7e20: 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28 53 TOINDEX (S
7e30: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20 QLITE_WARNING |
7e40: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (1<<8)).#define
7e50: 53 51 4c 49 54 45 5f 41 55 54 48 5f 55 53 45 52 SQLITE_AUTH_USER
7e60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 (
7e70: 53 51 4c 49 54 45 5f 41 55 54 48 20 7c 20 28 31 SQLITE_AUTH | (1
7e80: 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 <<8))../*.** CAP
7e90: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 I3REF: Flags For
7ea0: 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 File Open Opera
7eb0: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 tions.**.** Thes
7ec0: 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 e bit values are
7ed0: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 intended for us
7ee0: 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 e in the.** 3rd
7ef0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
7f00: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
7f10: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 2()] interface a
7f20: 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 nd.** in the 4th
7f30: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
7f40: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 e [sqlite3_vfs.x
7f50: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f Open] method..*/
7f60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
7f70: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 OPEN_READONLY
7f80: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0x00000001
7f90: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
7fa0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
7fb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
7fc0: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 OPEN_READWRITE
7fd0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0x00000002
7fe0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
7ff0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
8000: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
8010: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 OPEN_CREATE
8020: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0x00000004
8030: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
8040: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
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 44 45 4c 45 54 45 4f 4e 43 4c 4f OPEN_DELETEONCLO
8070: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38 SE 0x00000008
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 45 58 43 4c 55 53 49 56 45 20 20 OPEN_EXCLUSIVE
80b0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0x00000010
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 41 55 54 4f 50 52 4f 58 59 20 20 OPEN_AUTOPROXY
80f0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0x00000020
8100: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
8110: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
8120: 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20 OPEN_URI
8130: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0x00000040
8140: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
8150: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
8160: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
8170: 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 OPEN_MEMORY
8180: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0x00000080
8190: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
81a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
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 4d 41 49 4e 5f 44 42 20 20 20 20 OPEN_MAIN_DB
81d0: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0x00000100
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 45 4d 50 5f 44 42 20 20 20 20 OPEN_TEMP_DB
8210: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0x00000200
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 54 52 41 4e 53 49 45 4e 54 5f 44 OPEN_TRANSIENT_D
8250: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 B 0x00000400
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 4d 41 49 4e 5f 4a 4f 55 52 4e 41 OPEN_MAIN_JOURNA
8290: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30 L 0x00000800
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 54 45 4d 50 5f 4a 4f 55 52 4e 41 OPEN_TEMP_JOURNA
82d0: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30 L 0x00001000
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 53 55 42 4a 4f 55 52 4e 41 4c 20 OPEN_SUBJOURNAL
8310: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0x00002000
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 4d 41 53 54 45 52 5f 4a 4f 55 52 OPEN_MASTER_JOUR
8350: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 NAL 0x00004000
8360: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
8370: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
8380: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 OPEN_NOMUTEX
8390: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30 0x00008000
83a0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
83b0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
83c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
83d0: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 OPEN_FULLMUTEX
83e0: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30 0x00010000
83f0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
8400: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
8410: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
8420: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 OPEN_SHAREDCACHE
8430: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30 0x00020000
8440: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
8450: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
8460: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
8470: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 OPEN_PRIVATECACH
8480: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30 E 0x00040000
8490: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
84a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
84b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
84c0: 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 OPEN_WAL
84d0: 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30 0x00080000
84e0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
84f0: 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20 ../* Reserved:
8500: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
8510: 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30 0x00F0000
8520: 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 0 */../*.** CAPI
8530: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 3REF: Device Cha
8540: 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a racteristics.**.
8550: 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68 ** The xDeviceCh
8560: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 aracteristics me
8570: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c thod of the [sql
8580: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d ite3_io_methods]
8590: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 .** object retur
85a0: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 ns an integer wh
85b0: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 ich is a vector
85c0: 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 of these.** bit
85d0: 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e values expressin
85e0: 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 g I/O characteri
85f0: 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 stics of the mas
8600: 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 s storage.** dev
8610: 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 ice that holds t
8620: 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 he file that the
8630: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 [sqlite3_io_met
8640: 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 hods].** refers
8650: 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 to..**.** The SQ
8660: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
8670: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 C property means
8680: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 that all writes
8690: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 of.** any size
86a0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 are atomic. The
86b0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
86c0: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a OMICnnn values.*
86d0: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 * mean that writ
86e0: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 es of blocks tha
86f0: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 t are nnn bytes
8700: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 in size and.** a
8710: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e re aligned to an
8720: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 address which i
8730: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c s an integer mul
8740: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 tiple of.** nnn
8750: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 are atomic. The
8760: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 SQLITE_IOCAP_SA
8770: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 FE_APPEND value
8780: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 means.** that wh
8790: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e en data is appen
87a0: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 ded to a file, t
87b0: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e he data is appen
87c0: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 ded.** first the
87d0: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 n the size of th
87e0: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 e file is extend
87f0: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 ed, never the ot
8800: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e her.** way aroun
8810: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 d. The SQLITE_I
8820: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 OCAP_SEQUENTIAL
8830: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 property means t
8840: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 hat.** informati
8850: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f on is written to
8860: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d disk in the sam
8870: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 e order as calls
8880: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e .** to xWrite().
8890: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 The SQLITE_IOC
88a0: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 AP_POWERSAFE_OVE
88b0: 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 79 20 RWRITE property
88c0: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 means that.** af
88d0: 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f ter reboot follo
88e0: 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20 wing a crash or
88f0: 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 power loss, the
8900: 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a only bytes in a.
8910: 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65 72 ** file that wer
8920: 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 68 65 e written at the
8930: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 application lev
8940: 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63 68 el might have ch
8950: 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 anged.** and tha
8960: 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73 t adjacent bytes
8970: 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 69 74 , even bytes wit
8980: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63 hin the same sec
8990: 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 tor are.** guara
89a0: 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68 nteed to be unch
89b0: 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c 49 anged. The SQLI
89c0: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 TE_IOCAP_UNDELET
89d0: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a ABLE_WHEN_OPEN.*
89e0: 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65 20 * flag indicate
89f0: 74 68 61 74 20 61 20 66 69 6c 65 20 63 61 6e 6e that a file cann
8a00: 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20 77 68 ot be deleted wh
8a10: 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a en open. The.**
8a20: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d SQLITE_IOCAP_IM
8a30: 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 69 6e 64 MUTABLE flag ind
8a40: 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20 icates that the
8a50: 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65 file is on.** re
8a60: 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e ad-only media an
8a70: 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e d cannot be chan
8a80: 67 65 64 20 65 76 65 6e 20 62 79 20 70 72 6f 63 ged even by proc
8a90: 65 73 73 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c esses with.** el
8aa0: 65 76 61 74 65 64 20 70 72 69 76 69 6c 65 67 65 evated privilege
8ab0: 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 s..*/.#define SQ
8ac0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
8ad0: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 C
8ae0: 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 0x00000001.#de
8af0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
8b00: 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 P_ATOMIC512
8b10: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
8b20: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 002.#define SQLI
8b30: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 TE_IOCAP_ATOMIC1
8b40: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 K
8b50: 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 0x00000004.#defi
8b60: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
8b70: 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 ATOMIC2K
8b80: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 0x0000000
8b90: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 8.#define SQLITE
8ba0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 _IOCAP_ATOMIC4K
8bb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 0x
8bc0: 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 00000010.#define
8bd0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
8be0: 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20 20 OMIC8K
8bf0: 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 0x00000020.
8c00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
8c10: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 OCAP_ATOMIC16K
8c20: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
8c30: 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 000040.#define S
8c40: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
8c50: 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 20 20 IC32K
8c60: 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 0x00000080.#d
8c70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
8c80: 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 AP_ATOMIC64K
8c90: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
8ca0: 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0100.#define SQL
8cb0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 ITE_IOCAP_SAFE_A
8cc0: 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 20 20 PPEND
8cd0: 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 0x00000200.#def
8ce0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
8cf0: 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 _SEQUENTIAL
8d00: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 34 0x000004
8d10: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 00.#define SQLIT
8d20: 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 E_IOCAP_UNDELETA
8d30: 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 BLE_WHEN_OPEN 0
8d40: 78 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e x00000800.#defin
8d50: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 e SQLITE_IOCAP_P
8d60: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 OWERSAFE_OVERWRI
8d70: 54 45 20 20 20 20 30 78 30 30 30 30 31 30 30 30 TE 0x00001000
8d80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
8d90: 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 IOCAP_IMMUTABLE
8da0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 0x0
8db0: 30 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 0002000../*.** C
8dc0: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f API3REF: File Lo
8dd0: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a cking Levels.**.
8de0: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f ** SQLite uses o
8df0: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 ne of these inte
8e00: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 ger values as th
8e10: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 e second.** argu
8e20: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 ment to calls it
8e30: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c makes to the xL
8e40: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 ock() and xUnloc
8e50: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f k() methods.** o
8e60: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f f an [sqlite3_io
8e70: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 _methods] object
8e80: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
8e90: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 ITE_LOCK_NONE
8ea0: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 0.#define
8eb0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 SQLITE_LOCK_SHA
8ec0: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 RED 1.#de
8ed0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b fine SQLITE_LOCK
8ee0: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32 _RESERVED 2
8ef0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
8f00: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 LOCK_PENDING
8f10: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 3.#define SQL
8f20: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 ITE_LOCK_EXCLUSI
8f30: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 VE 4../*.**
8f40: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 CAPI3REF: Synchr
8f50: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 onization Type F
8f60: 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 lags.**.** When
8f70: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 SQLite invokes t
8f80: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f he xSync() metho
8f90: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 d of an.** [sqli
8fa0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 te3_io_methods]
8fb0: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 object it uses a
8fc0: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a combination of.
8fd0: 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 ** these integer
8fe0: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 values as the s
8ff0: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a econd argument..
9000: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 **.** When the S
9010: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f QLITE_SYNC_DATAO
9020: 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 NLY flag is used
9030: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 , it means that
9040: 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 the.** sync oper
9050: 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 ation only needs
9060: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 to flush data t
9070: 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 o mass storage.
9080: 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d Inode.** inform
9090: 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 ation need not b
90a0: 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 e flushed. If th
90b0: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 e lower four bit
90c0: 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a s of the flag.**
90d0: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 equal SQLITE_SY
90e0: 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 NC_NORMAL, that
90f0: 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 means to use nor
9100: 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 mal fsync() sema
9110: 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 ntics..** If the
9120: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 lower four bits
9130: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 equal SQLITE_SY
9140: 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 NC_FULL, that me
9150: 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 ans.** to use Ma
9160: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c c OS X style ful
9170: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 lsync instead of
9180: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 fsync()..**.**
9190: 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 Do not confuse t
91a0: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e he SQLITE_SYNC_N
91b0: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 ORMAL and SQLITE
91c0: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 _SYNC_FULL flags
91d0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 .** with the [PR
91e0: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 AGMA synchronous
91f0: 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 ]=NORMAL and [PR
9200: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 AGMA synchronous
9210: 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e ]=FULL.** settin
9220: 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 gs. The [synchr
9230: 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 onous pragma] de
9240: 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 termines when ca
9250: 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 lls to the.** xS
9260: 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f ync VFS method o
9270: 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 ccur and applies
9280: 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 uniformly acros
9290: 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e s all platforms.
92a0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 .** The SQLITE_S
92b0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 YNC_NORMAL and S
92c0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 QLITE_SYNC_FULL
92d0: 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 flags determine
92e0: 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 how.** energetic
92f0: 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 or rigorous or
9300: 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e forceful the syn
9310: 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 c operations are
9320: 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b and.** only mak
9330: 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f e a difference o
9340: 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 n Mac OSX for th
9350: 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 e default SQLite
9360: 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 code..** (Third
9370: 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 -party VFS imple
9380: 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 mentations might
9390: 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 also make the d
93a0: 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 istinction.** be
93b0: 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e tween SQLITE_SYN
93c0: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c C_NORMAL and SQL
93d0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 ITE_SYNC_FULL, b
93e0: 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 ut among the.**
93f0: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d operating system
9400: 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f s natively suppo
9410: 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 rted by SQLite,
9420: 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 only Mac OSX.**
9430: 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 cares about the
9440: 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a difference.).*/.
9450: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
9460: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 YNC_NORMAL
9470: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 0x00002.#defin
9480: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 e SQLITE_SYNC_FU
9490: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30 LL 0x00
94a0: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 003.#define SQLI
94b0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 TE_SYNC_DATAONLY
94c0: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 0x00010../
94d0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
94e0: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e S Interface Open
94f0: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a File Handle.**.
9500: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 ** An [sqlite3_f
9510: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 ile] object repr
9520: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 esents an open f
9530: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b ile in the .** [
9540: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 sqlite3_vfs | OS
9550: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 interface layer
9560: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f ]. Individual O
9570: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 S interface.** i
9580: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 mplementations w
9590: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 ill.** want to s
95a0: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a ubclass this obj
95b0: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 ect by appending
95c0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c additional fiel
95d0: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 ds.** for their
95e0: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d own use. The pM
95f0: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 ethods entry is
9600: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a a pointer to an.
9610: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d ** [sqlite3_io_m
9620: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 ethods] object t
9630: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 hat defines meth
9640: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 ods for performi
9650: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 ng.** I/O operat
9660: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e ions on the open
9670: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 file..*/.typede
9680: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
9690: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 _file sqlite3_fi
96a0: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 le;.struct sqlit
96b0: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 e3_file {. cons
96c0: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 t struct sqlite3
96d0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 _io_methods *pMe
96e0: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f thods; /* Metho
96f0: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 ds for an open f
9700: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a ile */.};../*.**
9710: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e CAPI3REF: OS In
9720: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 terface File Vir
9730: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a tual Methods Obj
9740: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 ect.**.** Every
9750: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 file opened by t
9760: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e he [sqlite3_vfs.
9770: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f xOpen] method po
9780: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 pulates an.** [s
9790: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a qlite3_file] obj
97a0: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f ect (or, more co
97b0: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 mmonly, a subcla
97c0: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 ss of the.** [sq
97d0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 lite3_file] obje
97e0: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 ct) with a point
97f0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 er to an instanc
9800: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 e of this object
9810: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 ..** This object
9820: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 defines the met
9830: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 hods used to per
9840: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 form various ope
9850: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e rations.** again
9860: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 st the open file
9870: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 represented by
9880: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c the [sqlite3_fil
9890: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a e] object..**.**
98a0: 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 If the [sqlite3
98b0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 _vfs.xOpen] meth
98c0: 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 od sets the sqli
98d0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 te3_file.pMethod
98e0: 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f s element .** to
98f0: 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e a non-NULL poin
9900: 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 ter, then the sq
9910: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
9920: 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a .xClose method.*
9930: 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 * may be invoked
9940: 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71 even if the [sq
9950: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d lite3_vfs.xOpen]
9960: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 reported that i
9970: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a t failed. The.*
9980: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 * only way to pr
9990: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 event a call to
99a0: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 xClose following
99b0: 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 a failed [sqlit
99c0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a e3_vfs.xOpen].**
99d0: 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c is for the [sql
99e0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 ite3_vfs.xOpen]
99f0: 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 to set the sqlit
9a00: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 e3_file.pMethods
9a10: 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e element.** to N
9a20: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 ULL..**.** The f
9a30: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f lags argument to
9a40: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e xSync may be on
9a50: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e e of [SQLITE_SYN
9a60: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 C_NORMAL] or.**
9a70: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c [SQLITE_SYNC_FUL
9a80: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 L]. The first c
9a90: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 hoice is the nor
9aa0: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 mal fsync()..**
9ab0: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 The second choic
9ac0: 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 e is a Mac OS X
9ad0: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 style fullsync.
9ae0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e The [SQLITE_SYN
9af0: 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 C_DATAONLY].** f
9b00: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 lag may be ORed
9b10: 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 in to indicate t
9b20: 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 hat only the dat
9b30: 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a a of the file.**
9b40: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f and not its ino
9b50: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 de needs to be s
9b60: 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ynced..**.** The
9b70: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 integer values
9b80: 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 to xLock() and x
9b90: 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 Unlock() are one
9ba0: 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c of.** <ul>.** <
9bb0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b li> [SQLITE_LOCK
9bc0: 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 _NONE],.** <li>
9bd0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 [SQLITE_LOCK_SHA
9be0: 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 RED],.** <li> [S
9bf0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 QLITE_LOCK_RESER
9c00: 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 VED],.** <li> [S
9c10: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 QLITE_LOCK_PENDI
9c20: 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 NG], or.** <li>
9c30: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 [SQLITE_LOCK_EXC
9c40: 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c LUSIVE]..** </ul
9c50: 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 >.** xLock() inc
9c60: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e reases the lock.
9c70: 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 xUnlock() decre
9c80: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a ases the lock..*
9c90: 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 * The xCheckRese
9ca0: 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f rvedLock() metho
9cb0: 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 d checks whether
9cc0: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f any database co
9cd0: 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 nnection,.** eit
9ce0: 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 her in this proc
9cf0: 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f ess or in some o
9d00: 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 ther process, is
9d10: 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 holding a RESER
9d20: 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c VED,.** PENDING,
9d30: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f or EXCLUSIVE lo
9d40: 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 ck on the file.
9d50: 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 It returns true
9d60: 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f .** if such a lo
9d70: 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 ck exists and fa
9d80: 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a lse otherwise..*
9d90: 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f *.** The xFileCo
9da0: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 ntrol() method i
9db0: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 s a generic inte
9dc0: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 rface that allow
9dd0: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 s custom.** VFS
9de0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
9df0: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 to directly cont
9e00: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 rol an open file
9e10: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 using the.** [s
9e20: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 qlite3_file_cont
9e30: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 rol()] interface
9e40: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f . The second "o
9e50: 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 p" argument is a
9e60: 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 n.** integer opc
9e70: 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 ode. The third
9e80: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 argument is a ge
9e90: 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e neric pointer in
9ea0: 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 tended to.** poi
9eb0: 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 nt to a structur
9ec0: 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 e that may conta
9ed0: 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 in arguments or
9ee0: 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 space in which t
9ef0: 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 o.** write retur
9f00: 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e n values. Poten
9f10: 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 tial uses for xF
9f20: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 ileControl() mig
9f30: 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f ht be.** functio
9f40: 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f ns to enable blo
9f50: 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 cking locks with
9f60: 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 timeouts, to ch
9f70: 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b ange the.** lock
9f80: 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f ing strategy (fo
9f90: 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 r example to use
9fa0: 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 dot-file locks)
9fb0: 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 , to inquire.**
9fc0: 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 about the status
9fd0: 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 of a lock, or t
9fe0: 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f o break stale lo
9ff0: 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 cks. The SQLite
a000: 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 .** core reserve
a010: 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 s all opcodes le
a020: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 ss than 100 for
a030: 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 its own use..**
a040: 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 A [file control
a050: 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f opcodes | list o
a060: 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 f opcodes] less
a070: 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 than 100 is avai
a080: 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 lable..** Applic
a090: 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 ations that defi
a0a0: 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c ne a custom xFil
a0b0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 eControl method
a0c0: 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 should use opcod
a0d0: 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 es.** greater th
a0e0: 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 an 100 to avoid
a0f0: 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20 conflicts. VFS
a100: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
a110: 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e should.** return
a120: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e [SQLITE_NOTFOUN
a130: 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 D] for file cont
a140: 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74 rol opcodes that
a150: 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 they do not.**
a160: 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a recognize..**.**
a170: 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 The xSectorSize
a180: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e () method return
a190: 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a s the sector siz
a1a0: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 e of the.** devi
a1b0: 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 ce that underlie
a1c0: 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 s the file. The
a1d0: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 sector size is
a1e0: 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 the.** minimum w
a1f0: 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 rite that can be
a200: 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f performed witho
a210: 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a ut disturbing.**
a220: 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 other bytes in
a230: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 the file. The x
a240: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 DeviceCharacteri
a250: 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f stics().** metho
a260: 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 d returns a bit
a270: 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e vector describin
a280: 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 g behaviors of t
a290: 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 he.** underlying
a2a0: 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c device:.**.** <
a2b0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c ul>.** <li> [SQL
a2c0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
a2d0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
a2e0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 E_IOCAP_ATOMIC51
a2f0: 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 2].** <li> [SQLI
a300: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 TE_IOCAP_ATOMIC1
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 32 TE_IOCAP_ATOMIC2
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 34 TE_IOCAP_ATOMIC4
a350: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
a360: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 TE_IOCAP_ATOMIC8
a370: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
a380: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 TE_IOCAP_ATOMIC1
a390: 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 6K].** <li> [SQL
a3a0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
a3b0: 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 32K].** <li> [SQ
a3c0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
a3d0: 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 C64K].** <li> [S
a3e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 QLITE_IOCAP_SAFE
a3f0: 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e _APPEND].** <li>
a400: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 [SQLITE_IOCAP_S
a410: 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f EQUENTIAL].** </
a420: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 ul>.**.** The SQ
a430: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
a440: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 C property means
a450: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 that all writes
a460: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 of.** any size
a470: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 are atomic. The
a480: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
a490: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a OMICnnn values.*
a4a0: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 * mean that writ
a4b0: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 es of blocks tha
a4c0: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 t are nnn bytes
a4d0: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 in size and.** a
a4e0: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e re aligned to an
a4f0: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 address which i
a500: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c s an integer mul
a510: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 tiple of.** nnn
a520: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 are atomic. The
a530: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 SQLITE_IOCAP_SA
a540: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 FE_APPEND value
a550: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 means.** that wh
a560: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e en data is appen
a570: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 ded to a file, t
a580: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e he data is appen
a590: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 ded.** first the
a5a0: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 n the size of th
a5b0: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 e file is extend
a5c0: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 ed, never the ot
a5d0: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e her.** way aroun
a5e0: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 d. The SQLITE_I
a5f0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 OCAP_SEQUENTIAL
a600: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 property means t
a610: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 hat.** informati
a620: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f on is written to
a630: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d disk in the sam
a640: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 e order as calls
a650: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e .** to xWrite().
a660: 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 .**.** If xRead(
a670: 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 ) returns SQLITE
a680: 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 _IOERR_SHORT_REA
a690: 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 D it must also f
a6a0: 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e ill.** in the un
a6b0: 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 read portions of
a6c0: 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68 the buffer with
a6d0: 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 zeros. A VFS t
a6e0: 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 hat.** fails to
a6f0: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 zero-fill short
a700: 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d reads might seem
a710: 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 to work. Howev
a720: 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 er,.** failure t
a730: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 o zero-fill shor
a740: 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 t reads will eve
a750: 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a ntually lead to.
a760: 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 ** database corr
a770: 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 uption..*/.typed
a780: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
a790: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 3_io_methods sql
a7a0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b ite3_io_methods;
a7b0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f .struct sqlite3_
a7c0: 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 io_methods {. i
a7d0: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 nt iVersion;. i
a7e0: 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c nt (*xClose)(sql
a7f0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 ite3_file*);. i
a800: 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 nt (*xRead)(sqli
a810: 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a te3_file*, void*
a820: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 , int iAmt, sqli
a830: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 te3_int64 iOfst)
a840: 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 ;. int (*xWrite
a850: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
a860: 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e const void*, in
a870: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f t iAmt, sqlite3_
a880: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 int64 iOfst);.
a890: 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 int (*xTruncate)
a8a0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
a8b0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 sqlite3_int64 si
a8c0: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 ze);. int (*xSy
a8d0: 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 nc)(sqlite3_file
a8e0: 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 *, int flags);.
a8f0: 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 int (*xFileSize
a900: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
a910: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a sqlite3_int64 *
a920: 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a pSize);. int (*
a930: 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 xLock)(sqlite3_f
a940: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e ile*, int);. in
a950: 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c t (*xUnlock)(sql
a960: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 ite3_file*, int)
a970: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b ;. int (*xCheck
a980: 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 ReservedLock)(sq
a990: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 lite3_file*, int
a9a0: 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e *pResOut);. in
a9b0: 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c t (*xFileControl
a9c0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
a9d0: 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 int op, void *p
a9e0: 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 Arg);. int (*xS
a9f0: 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 ectorSize)(sqlit
aa00: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 e3_file*);. int
aa10: 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 (*xDeviceCharac
aa20: 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 teristics)(sqlit
aa30: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 e3_file*);. /*
aa40: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 Methods above ar
aa50: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 e valid for vers
aa60: 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 ion 1 */. int (
aa70: 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 *xShmMap)(sqlite
aa80: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 3_file*, int iPg
aa90: 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c , int pgsz, int,
aaa0: 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a void volatile**
aab0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c );. int (*xShmL
aac0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ock)(sqlite3_fil
aad0: 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 e*, int offset,
aae0: 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 int n, int flags
aaf0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d );. void (*xShm
ab00: 42 61 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 Barrier)(sqlite3
ab10: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 _file*);. int (
ab20: 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 *xShmUnmap)(sqli
ab30: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 te3_file*, int d
ab40: 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a eleteFlag);. /*
ab50: 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 Methods above a
ab60: 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 re valid for ver
ab70: 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 sion 2 */. int
ab80: 28 2a 78 46 65 74 63 68 29 28 73 71 6c 69 74 65 (*xFetch)(sqlite
ab90: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 3_file*, sqlite3
aba0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e _int64 iOfst, in
abb0: 74 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 t iAmt, void **p
abc0: 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 p);. int (*xUnf
abd0: 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 etch)(sqlite3_fi
abe0: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 le*, sqlite3_int
abf0: 36 34 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 64 iOfst, void *
ac00: 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 p);. /* Methods
ac10: 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 above are valid
ac20: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a for version 3 *
ac30: 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 /. /* Additiona
ac40: 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 l methods may be
ac50: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 added in future
ac60: 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a releases */.};.
ac70: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
ac80: 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 Standard File C
ac90: 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a ontrol Opcodes.*
aca0: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c * KEYWORDS: {fil
acb0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 e control opcode
acc0: 73 7d 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c s} {file control
acd0: 20 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 opcode}.**.** T
ace0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e hese integer con
acf0: 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 stants are opcod
ad00: 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 es for the xFile
ad10: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a Control method.*
ad20: 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 * of the [sqlite
ad30: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 3_io_methods] ob
ad40: 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 ject and for the
ad50: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 [sqlite3_file_c
ad60: 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 ontrol()].** int
ad70: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 erface..**.** <u
ad80: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 l>.** <li>[[SQLI
ad90: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 TE_FCNTL_LOCKSTA
ada0: 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c TE]].** The [SQL
adb0: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 ITE_FCNTL_LOCKST
adc0: 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 ATE] opcode is u
add0: 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e sed for debuggin
ade0: 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f g. This.** opco
adf0: 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 de causes the xF
ae00: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f ileControl metho
ae10: 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 d to write the c
ae20: 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a urrent state of.
ae30: 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 ** the lock (one
ae40: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b of [SQLITE_LOCK
ae50: 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f _NONE], [SQLITE_
ae60: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a LOCK_SHARED],.**
ae70: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 [SQLITE_LOCK_RE
ae80: 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 SERVED], [SQLITE
ae90: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 _LOCK_PENDING],
aea0: 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f or [SQLITE_LOCK_
aeb0: 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 EXCLUSIVE]).** i
aec0: 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 nto an integer t
aed0: 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67 hat the pArg arg
aee0: 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e ument points to.
aef0: 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 This capability
af00: 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 .** is used duri
af10: 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 69 ng testing and i
af20: 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 s only available
af30: 20 77 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 when the SQLITE
af40: 5f 54 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 _TEST.** compile
af50: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 -time option is
af60: 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e used..**.** <li>
af70: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 [[SQLITE_FCNTL_S
af80: 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 IZE_HINT]].** Th
af90: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
afa0: 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 SIZE_HINT] opcod
afb0: 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c e is used by SQL
afc0: 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 ite to give the
afd0: 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 VFS.** layer a h
afe0: 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 int of how large
aff0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
b000: 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 le will grow to
b010: 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a be during the.**
b020: 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 current transac
b030: 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 tion. This hint
b040: 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 is not guarante
b050: 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 ed to be accurat
b060: 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f e but it.** is o
b070: 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 ften close. The
b080: 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 underlying VFS
b090: 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 might choose to
b0a0: 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 preallocate data
b0b0: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 base.** file spa
b0c0: 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 ce based on this
b0d0: 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 hint in order t
b0e0: 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f o help writes to
b0f0: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a the database.**
b100: 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 file run faster
b110: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
b120: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b LITE_FCNTL_CHUNK
b130: 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b _SIZE]].** The [
b140: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 SQLITE_FCNTL_CHU
b150: 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 NK_SIZE] opcode
b160: 69 73 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 is used to reque
b170: 73 74 20 74 68 61 74 20 74 68 65 20 56 46 53 0a st that the VFS.
b180: 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 ** extends and t
b190: 72 75 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 runcates the dat
b1a0: 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 abase file in ch
b1b0: 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 unks of a size s
b1c0: 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 pecified.** by t
b1d0: 68 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 he user. The fou
b1e0: 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rth argument to
b1f0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f [sqlite3_file_co
b200: 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 ntrol()] should
b210: 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 .** point to an
b220: 69 6e 74 65 67 65 72 20 28 74 79 70 65 20 69 6e integer (type in
b230: 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 t) containing th
b240: 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 e new chunk-size
b250: 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 to use.** for t
b260: 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 he nominated dat
b270: 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e abase. Allocatin
b280: 67 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 g database file
b290: 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a space in large.*
b2a0: 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d * chunks (say 1M
b2b0: 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 B at a time), ma
b2c0: 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 y reduce file-sy
b2d0: 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 stem fragmentati
b2e0: 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 on and.** improv
b2f0: 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e e performance on
b300: 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a some systems..*
b310: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
b320: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 E_FCNTL_FILE_POI
b330: 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 NTER]].** The [S
b340: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 QLITE_FCNTL_FILE
b350: 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 _POINTER] opcode
b360: 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 is used to obta
b370: 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 in a pointer.**
b380: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
b390: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 file] object ass
b3a0: 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70 ociated with a p
b3b0: 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 articular databa
b3c0: 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e se.** connection
b3d0: 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69 . See the [sqli
b3e0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
b3f0: 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f ()] documentatio
b400: 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f n for.** additio
b410: 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e nal information.
b420: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
b430: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f ITE_FCNTL_SYNC_O
b440: 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c MITTED]].** No l
b450: 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a onger in use..**
b460: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
b470: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a _FCNTL_SYNC]].**
b480: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e The [SQLITE_FCN
b490: 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20 TL_SYNC] opcode
b4a0: 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 is generated int
b4b0: 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 ernally by SQLit
b4c0: 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f e and.** sent to
b4d0: 20 74 68 65 20 56 46 53 20 69 6d 6d 65 64 69 61 the VFS immedia
b4e0: 74 65 6c 79 20 62 65 66 6f 72 65 20 74 68 65 20 tely before the
b4f0: 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 xSync method is
b500: 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 invoked on a.**
b510: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 64 65 database file de
b520: 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66 scriptor. Or, if
b530: 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f the xSync metho
b540: 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 d is not invoked
b550: 20 0a 2a 2a 20 62 65 63 61 75 73 65 20 74 68 65 .** because the
b560: 20 75 73 65 72 20 68 61 73 20 63 6f 6e 66 69 67 user has config
b570: 75 72 65 64 20 53 51 4c 69 74 65 20 77 69 74 68 ured SQLite with
b580: 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e .** [PRAGMA syn
b590: 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d chronous | PRAGM
b5a0: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 A synchronous=OF
b5b0: 46 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 F] it is invoked
b5c0: 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 in place .** of
b5d0: 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f the xSync metho
b5e0: 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73 65 73 d. In most cases
b5f0: 2c 20 74 68 65 20 70 6f 69 6e 74 65 72 20 61 72 , the pointer ar
b600: 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 77 69 gument passed wi
b610: 74 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d th.** this file-
b620: 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e control is NULL.
b630: 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68 65 However, if the
b640: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 database file i
b650: 73 20 62 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a s being synced.*
b660: 2a 20 61 73 20 70 61 72 74 20 6f 66 20 61 20 6d * as part of a m
b670: 75 6c 74 69 2d 64 61 74 61 62 61 73 65 20 63 6f ulti-database co
b680: 6d 6d 69 74 2c 20 74 68 65 20 61 72 67 75 6d 65 mmit, the argume
b690: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e nt points to a n
b6a0: 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a ul-terminated.**
b6b0: 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 string containi
b6c0: 6e 67 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 ng the transacti
b6d0: 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e ons master-journ
b6e0: 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46 al file name. VF
b6f0: 53 65 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20 Ses that .** do
b700: 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 not need this si
b710: 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65 gnal should sile
b720: 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 ntly ignore this
b730: 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 opcode. Applica
b740: 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 tions .** should
b750: 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 not call [sqlit
b760: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 e3_file_control(
b770: 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 )] with this opc
b780: 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 ode as doing so
b790: 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75 70 74 20 may .** disrupt
b7a0: 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 the operation of
b7b0: 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 the specialized
b7c0: 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 VFSes that do r
b7d0: 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a equire it. .**.
b7e0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
b7f0: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 FCNTL_COMMIT_PHA
b800: 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b SETWO]].** The [
b810: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d SQLITE_FCNTL_COM
b820: 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70 MIT_PHASETWO] op
b830: 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 code is generate
b840: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 d internally by
b850: 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65 SQLite.** and se
b860: 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 61 66 nt to the VFS af
b870: 74 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f ter a transactio
b880: 6e 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69 n has been commi
b890: 74 74 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 tted immediately
b8a0: 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72 65 20 74 .** but before t
b8b0: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 75 he database is u
b8c0: 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73 20 74 nlocked. VFSes t
b8d0: 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 hat do not need
b8e0: 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 this signal.** s
b8f0: 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 hould silently i
b900: 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 gnore this opcod
b910: 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 e. Applications
b920: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a should not call.
b930: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 ** [sqlite3_file
b940: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 _control()] with
b950: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 this opcode as
b960: 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 doing so may dis
b970: 72 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65 rupt the .** ope
b980: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 ration of the sp
b990: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 ecialized VFSes
b9a0: 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 that do require
b9b0: 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e it. .**.** <li>
b9c0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 [[SQLITE_FCNTL_W
b9d0: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a IN32_AV_RETRY]].
b9e0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f ** ^The [SQLITE_
b9f0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 FCNTL_WIN32_AV_R
ba00: 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 ETRY] opcode is
ba10: 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 used to configur
ba20: 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 e automatic.** r
ba30: 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 etry counts and
ba40: 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 intervals for ce
ba50: 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f rtain disk I/O o
ba60: 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 perations for th
ba70: 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 e.** windows [VF
ba80: 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 S] in order to p
ba90: 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 rovide robustnes
baa0: 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63 s in the presenc
bab0: 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 e of.** anti-vir
bac0: 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 us programs. By
bad0: 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 default, the wi
bae0: 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 ndows VFS will r
baf0: 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a etry file read,.
bb00: 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 ** file write, a
bb10: 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f nd file delete o
bb20: 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 perations up to
bb30: 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61 10 times, with a
bb40: 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 delay.** of 25
bb50: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 milliseconds bef
bb60: 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 72 65 ore the first re
bb70: 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 68 65 try and with the
bb80: 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e delay increasin
bb90: 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74 g.** by an addit
bba0: 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 ional 25 millise
bbb0: 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68 20 conds with each
bbc0: 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 72 79 subsequent retry
bbd0: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 . This.** opcod
bbe0: 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 e allows these t
bbf0: 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72 65 wo values (10 re
bc00: 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c tries and 25 mil
bc10: 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c liseconds of del
bc20: 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a ay).** to be adj
bc30: 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75 usted. The valu
bc40: 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 20 66 es are changed f
bc50: 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 or all database
bc60: 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 connections.** w
bc70: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 ithin the same p
bc80: 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72 67 rocess. The arg
bc90: 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 ument is a point
bca0: 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f er to an array o
bcb0: 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 f two.** integer
bcc0: 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73 s where the firs
bcd0: 74 20 69 6e 74 65 67 65 72 20 69 20 74 68 65 20 t integer i the
bce0: 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20 new retry count
bcf0: 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a and the second.*
bd00: 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 * integer is the
bd10: 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68 delay. If eith
bd20: 65 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65 er integer is ne
bd30: 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 gative, then the
bd40: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e setting.** is n
bd50: 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 69 ot changed but i
bd60: 6e 73 74 65 61 64 20 74 68 65 20 70 72 69 6f 72 nstead the prior
bd70: 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73 value of that s
bd80: 65 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 65 etting is writte
bd90: 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 n.** into the ar
bda0: 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 ray entry, allow
bdb0: 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 20 ing the current
bdc0: 72 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 74 retry settings t
bdd0: 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 o be.** interrog
bde0: 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 ated. The zDbNa
bdf0: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 me parameter is
be00: 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c ignored..**.** <
be10: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
be20: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a L_PERSIST_WAL]].
be30: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f ** ^The [SQLITE_
be40: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 FCNTL_PERSIST_WA
be50: 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 L] opcode is use
be60: 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 d to set or quer
be70: 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 y the.** persist
be80: 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 ent [WAL | Write
be90: 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 Ahead Log] sett
bea0: 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 ing. By default
beb0: 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a , the auxiliary.
bec0: 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 6c ** write ahead l
bed0: 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 og and shared me
bee0: 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64 20 mory files used
bef0: 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 for transaction
bf00: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 control.** are a
bf10: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c utomatically del
bf20: 65 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 eted when the la
bf30: 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 test connection
bf40: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a to the database.
bf50: 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 ** closes. Sett
bf60: 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 ing persistent W
bf70: 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 AL mode causes t
bf80: 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 hose files to pe
bf90: 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 rsist after.** c
bfa0: 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e lose. Persistin
bfb0: 67 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 g the files is u
bfc0: 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 seful when other
bfd0: 20 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 processes that
bfe0: 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 do not.** have w
bff0: 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 rite permission
c000: 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 on the directory
c010: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 containing the
c020: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 database file wa
c030: 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 nt.** to read th
c040: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c e database file,
c050: 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 as the WAL and
c060: 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 shared memory fi
c070: 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a les must exist.*
c080: 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 * in order for t
c090: 68 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 he database to b
c0a0: 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 e readable. The
c0b0: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
c0c0: 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 r to.** [sqlite3
c0d0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d _file_control()]
c0e0: 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 for this opcode
c0f0: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 should be a poi
c100: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 nter to an integ
c110: 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 er..** That inte
c120: 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 ger is 0 to disa
c130: 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 ble persistent W
c140: 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 AL mode or 1 to
c150: 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e enable persisten
c160: 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 t.** WAL mode.
c170: 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 If the integer i
c180: 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 s -1, then it is
c190: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 overwritten wit
c1a0: 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a h the current.**
c1b0: 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 WAL persistence
c1c0: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 setting..**.**
c1d0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
c1e0: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 TL_POWERSAFE_OVE
c1f0: 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 RWRITE]].** ^The
c200: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 [SQLITE_FCNTL_P
c210: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 OWERSAFE_OVERWRI
c220: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 TE] opcode is us
c230: 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 ed to set or que
c240: 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 ry the.** persis
c250: 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d tent "powersafe-
c260: 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 50 overwrite" or "P
c270: 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54 SOW" setting. T
c280: 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a he PSOW setting.
c290: 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 ** determines th
c2a0: 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f e [SQLITE_IOCAP_
c2b0: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 POWERSAFE_OVERWR
c2c0: 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a ITE] bit of the.
c2d0: 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 63 ** xDeviceCharac
c2e0: 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 teristics method
c2f0: 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 s. The fourth pa
c300: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 rameter to.** [s
c310: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 qlite3_file_cont
c320: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 rol()] for this
c330: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 opcode should be
c340: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
c350: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 integer..** Tha
c360: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 t integer is 0 t
c370: 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 o disable zero-d
c380: 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 amage mode or 1
c390: 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 to enable zero-d
c3a0: 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 amage.** mode.
c3b0: 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 If the integer i
c3c0: 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 s -1, then it is
c3d0: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 overwritten wit
c3e0: 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a h the current.**
c3f0: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 zero-damage mod
c400: 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a e setting..**.**
c410: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
c420: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a NTL_OVERWRITE]].
c430: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f ** ^The [SQLITE_
c440: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d FCNTL_OVERWRITE]
c450: 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b opcode is invok
c460: 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 ed by SQLite aft
c470: 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 er opening.** a
c480: 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f write transactio
c490: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 n to indicate th
c4a0: 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 at, unless it is
c4b0: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 rolled back for
c4c0: 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c some.** reason,
c4d0: 20 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 the entire data
c4e0: 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 base file will b
c4f0: 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 e overwritten by
c500: 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a the current .**
c510: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 transaction. Th
c520: 69 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41 is is used by VA
c530: 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e CUUM operations.
c540: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
c550: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d ITE_FCNTL_VFSNAM
c560: 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c E]].** ^The [SQL
c570: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d ITE_FCNTL_VFSNAM
c580: 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 E] opcode can be
c590: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 used to obtain
c5a0: 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 the names of.**
c5b0: 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 all [VFSes] in t
c5c0: 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 he VFS stack. T
c5d0: 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 he names are of
c5e0: 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e all VFS shims an
c5f0: 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 d the.** final b
c600: 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 ottom-level VFS
c610: 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f are written into
c620: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 memory obtained
c630: 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 from .** [sqlit
c640: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 e3_malloc()] and
c650: 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 the result is s
c660: 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 tored in the cha
c670: 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 r* variable.** t
c680: 68 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 hat the fourth p
c690: 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c arameter of [sql
c6a0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
c6b0: 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a l()] points to..
c6c0: 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 ** The caller is
c6d0: 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 responsible for
c6e0: 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d freeing the mem
c6f0: 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 ory when done.
c700: 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 As with.** all f
c710: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 ile-control acti
c720: 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f ons, there is no
c730: 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 guarantee that
c740: 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c this will actual
c750: 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e ly.** do anythin
c760: 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 g. Callers shou
c770: 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 ld initialize th
c780: 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 e char* variable
c790: 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f to a NULL.** po
c7a0: 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 inter in case th
c7b0: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 is file-control
c7c0: 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 is not implement
c7d0: 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 ed. This file-c
c7e0: 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 ontrol.** is int
c7f0: 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f ended for diagno
c800: 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a stic use only..*
c810: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
c820: 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e E_FCNTL_VFS_POIN
c830: 54 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 TER]].** ^The [S
c840: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f QLITE_FCNTL_VFS_
c850: 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 POINTER] opcode
c860: 66 69 6e 64 73 20 61 20 70 6f 69 6e 74 65 72 20 finds a pointer
c870: 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c to the top-level
c880: 0a 2a 2a 20 5b 56 46 53 65 73 5d 20 63 75 72 72 .** [VFSes] curr
c890: 65 6e 74 6c 79 20 69 6e 20 75 73 65 2e 20 20 5e ently in use. ^
c8a0: 28 54 68 65 20 61 72 67 75 6d 65 6e 74 20 58 20 (The argument X
c8b0: 69 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 in.** sqlite3_fi
c8c0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 64 62 2c 53 51 le_control(db,SQ
c8d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 LITE_FCNTL_VFS_P
c8e0: 4f 49 4e 54 45 52 2c 58 29 20 6d 75 73 74 20 62 OINTER,X) must b
c8f0: 65 0a 2a 2a 20 6f 66 20 74 79 70 65 20 22 5b 73 e.** of type "[s
c900: 71 6c 69 74 65 33 5f 76 66 73 5d 20 2a 2a 22 2e qlite3_vfs] **".
c910: 20 20 54 68 69 73 20 6f 70 63 6f 64 65 73 20 77 This opcodes w
c920: 69 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a 20 74 6f ill set *X.** to
c930: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
c940: 65 20 74 6f 70 2d 6c 65 76 65 6c 20 56 46 53 2e e top-level VFS.
c950: 29 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 72 )^.** ^When ther
c960: 65 20 61 72 65 20 6d 75 6c 74 69 70 6c 65 20 56 e are multiple V
c970: 46 53 20 73 68 69 6d 73 20 69 6e 20 74 68 65 20 FS shims in the
c980: 73 74 61 63 6b 2c 20 74 68 69 73 20 6f 70 63 6f stack, this opco
c990: 64 65 20 66 69 6e 64 73 20 74 68 65 0a 2a 2a 20 de finds the.**
c9a0: 75 70 70 65 72 2d 6d 6f 73 74 20 73 68 69 6d 20 upper-most shim
c9b0: 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e only..**.** <li>
c9c0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 [[SQLITE_FCNTL_P
c9d0: 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e RAGMA]].** ^When
c9e0: 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 ever a [PRAGMA]
c9f0: 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 statement is par
ca00: 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f sed, an [SQLITE_
ca10: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a FCNTL_PRAGMA] .*
ca20: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 * file control i
ca30: 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 s sent to the op
ca40: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 en [sqlite3_file
ca50: 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 ] object corresp
ca60: 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 onding.** to the
ca70: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 database file t
ca80: 6f 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67 o which the prag
ca90: 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 ma statement ref
caa0: 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 ers. ^The argume
cab0: 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 nt.** to the [SQ
cac0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d LITE_FCNTL_PRAGM
cad0: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 A] file control
cae0: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a is an array of.*
caf0: 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 * pointers to st
cb00: 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 rings (char**) i
cb10: 6e 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f n which the seco
cb20: 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 nd element of th
cb30: 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 e array.** is th
cb40: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 e name of the pr
cb50: 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 agma and the thi
cb60: 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 rd element is th
cb70: 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 e argument to th
cb80: 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e e.** pragma or N
cb90: 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d ULL if the pragm
cba0: 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e a has no argumen
cbb0: 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 t. ^The handler
cbc0: 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 for an.** [SQLI
cbd0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d TE_FCNTL_PRAGMA]
cbe0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 file control ca
cbf0: 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b n optionally mak
cc00: 65 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d e the first elem
cc10: 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 ent.** of the ch
cc20: 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f ar** argument po
cc30: 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 int to a string
cc40: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 obtained from [s
cc50: 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 qlite3_mprintf()
cc60: 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 ].** or the equi
cc70: 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 valent and that
cc80: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f string will beco
cc90: 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 me the result of
cca0: 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a the pragma or.*
ccb0: 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 * the error mess
ccc0: 61 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d age if the pragm
ccd0: 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 a fails. ^If the
cce0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 .** [SQLITE_FCNT
ccf0: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 L_PRAGMA] file c
cd00: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b ontrol returns [
cd10: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d SQLITE_NOTFOUND]
cd20: 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a , then normal .*
cd30: 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 * [PRAGMA] proce
cd40: 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e ssing continues.
cd50: 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 ^If the [SQLIT
cd60: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a E_FCNTL_PRAGMA].
cd70: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 ** file control
cd80: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
cd90: 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 OK], then the pa
cda0: 72 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 rser assumes tha
cdb0: 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 t the.** VFS has
cdc0: 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 handled the PRA
cdd0: 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 GMA itself and t
cde0: 68 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 he parser genera
cdf0: 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 tes a no-op.** p
ce00: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
ce10: 74 20 69 66 20 72 65 73 75 6c 74 20 73 74 72 69 t if result stri
ce20: 6e 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72 20 74 ng is NULL, or t
ce30: 68 61 74 20 72 65 74 75 72 6e 73 20 61 20 63 6f hat returns a co
ce40: 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 py.** of the res
ce50: 75 6c 74 20 73 74 72 69 6e 67 20 69 66 20 74 68 ult string if th
ce60: 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 6e 2d e string is non-
ce70: 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 NULL..** ^If the
ce80: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 [SQLITE_FCNTL_P
ce90: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 RAGMA] file cont
cea0: 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 rol returns.** a
ceb0: 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f ny result code o
cec0: 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 ther than [SQLIT
ced0: 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 E_OK] or [SQLITE
cee0: 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 _NOTFOUND], that
cef0: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 means.** that t
cf00: 68 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 he VFS encounter
cf10: 65 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c ed an error whil
cf20: 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b e handling the [
cf30: 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a PRAGMA] and the.
cf40: 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f ** compilation o
cf50: 66 20 74 68 65 20 50 52 41 47 4d 41 20 66 61 69 f the PRAGMA fai
cf60: 6c 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 ls with an error
cf70: 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f . ^The [SQLITE_
cf80: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a FCNTL_PRAGMA].**
cf90: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 file control oc
cfa0: 63 75 72 73 20 61 74 20 74 68 65 20 62 65 67 69 curs at the begi
cfb0: 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 nning of pragma
cfc0: 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 statement analys
cfd0: 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 is and so.** it
cfe0: 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 is able to overr
cff0: 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 ide built-in [PR
d000: 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 AGMA] statements
d010: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
d020: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 LITE_FCNTL_BUSYH
d030: 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 ANDLER]].** ^The
d040: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 [SQLITE_FCNTL_B
d050: 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 USYHANDLER].** f
d060: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 ile-control may
d070: 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 be invoked by SQ
d080: 4c 69 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61 Lite on the data
d090: 62 61 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 base file handle
d0a0: 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65 .** shortly afte
d0b0: 72 20 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69 r it is opened i
d0c0: 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 n order to provi
d0d0: 64 65 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20 de a custom VFS
d0e0: 77 69 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 with access.** t
d0f0: 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e o the connection
d100: 73 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 s busy-handler c
d110: 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67 allback. The arg
d120: 75 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65 ument is of type
d130: 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 (void **).** -
d140: 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20 an array of two
d150: 28 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e (void *) values.
d160: 20 54 68 65 20 66 69 72 73 74 20 28 76 6f 69 64 The first (void
d170: 20 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 *) actually poi
d180: 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 nts.** to a func
d190: 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e tion of type (in
d1a0: 74 20 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 t (*)(void *)).
d1b0: 49 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f In order to invo
d1c0: 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f ke the connectio
d1d0: 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c ns.** busy-handl
d1e0: 65 72 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f er, this functio
d1f0: 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f n should be invo
d200: 6b 65 64 20 77 69 74 68 20 74 68 65 20 73 65 63 ked with the sec
d210: 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a ond (void *) in.
d220: 2a 2a 20 74 68 65 20 61 72 72 61 79 20 61 73 20 ** the array as
d230: 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e the only argumen
d240: 74 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 t. If it returns
d250: 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 non-zero, then
d260: 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a the operation.**
d270: 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69 should be retri
d280: 65 64 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e ed. If it return
d290: 73 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74 s zero, the cust
d2a0: 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62 om VFS should ab
d2b0: 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 andon the.** cur
d2c0: 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a rent operation..
d2d0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
d2e0: 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c TE_FCNTL_TEMPFIL
d2f0: 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c ENAME]].** ^Appl
d300: 69 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f ication can invo
d310: 6b 65 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 ke the [SQLITE_F
d320: 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d CNTL_TEMPFILENAM
d330: 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a E] file-control.
d340: 2a 2a 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 ** to have SQLit
d350: 65 20 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 e generate a.**
d360: 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 temporary filena
d370: 6d 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d me using the sam
d380: 65 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 e algorithm that
d390: 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 is followed to
d3a0: 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 generate.** temp
d3b0: 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 orary filenames
d3c0: 66 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 for TEMP tables
d3d0: 61 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e and other intern
d3e0: 61 6c 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a al uses. The.**
d3f0: 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 argument should
d400: 20 62 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 be a char** whi
d410: 63 68 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 ch will be fille
d420: 64 20 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e d with the filen
d430: 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 ame.** written i
d440: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 nto memory obtai
d450: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 ned from [sqlite
d460: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 3_malloc()]. Th
d470: 65 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a e caller should.
d480: 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 ** invoke [sqlit
d490: 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 e3_free()] on th
d4a0: 65 20 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 e result to avoi
d4b0: 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e d a memory leak.
d4c0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
d4d0: 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 ITE_FCNTL_MMAP_S
d4e0: 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 IZE]].** The [SQ
d4f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f LITE_FCNTL_MMAP_
d500: 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 SIZE] file contr
d510: 6f 6c 20 69 73 20 75 73 65 64 20 74 6f 20 71 75 ol is used to qu
d520: 65 72 79 20 6f 72 20 73 65 74 20 74 68 65 0a 2a ery or set the.*
d530: 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 * maximum number
d540: 20 6f 66 20 62 79 74 65 73 20 74 68 61 74 20 77 of bytes that w
d550: 69 6c 6c 20 62 65 20 75 73 65 64 20 66 6f 72 20 ill be used for
d560: 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f memory-mapped I/
d570: 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 O..** The argume
d580: 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 nt is a pointer
d590: 74 6f 20 61 20 76 61 6c 75 65 20 6f 66 20 74 79 to a value of ty
d5a0: 70 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 pe sqlite3_int64
d5b0: 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 that.** is an a
d5c0: 64 76 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 dvisory maximum
d5d0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
d5e0: 69 6e 20 74 68 65 20 66 69 6c 65 20 74 6f 20 6d in the file to m
d5f0: 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68 65 0a emory map. The.
d600: 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 ** pointer is ov
d610: 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 erwritten with t
d620: 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 he old value. T
d630: 68 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 he limit is not
d640: 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 changed if.** th
d650: 65 20 76 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c e value original
d660: 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 ly pointed to is
d670: 20 6e 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73 negative, and s
d680: 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69 o the current li
d690: 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 mit .** can be q
d6a0: 75 65 72 69 65 64 20 62 79 20 70 61 73 73 69 6e ueried by passin
d6b0: 67 20 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 g in a pointer t
d6c0: 6f 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d o a negative num
d6d0: 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 ber. This.** fi
d6e0: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 le-control is us
d6f0: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f ed internally to
d700: 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 implement [PRAG
d710: 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a MA mmap_size]..*
d720: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
d730: 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a E_FCNTL_TRACE]].
d740: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 ** The [SQLITE_F
d750: 43 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 CNTL_TRACE] file
d760: 20 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 control provide
d770: 73 20 61 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 s advisory infor
d780: 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 mation.** to the
d790: 20 56 46 53 20 61 62 6f 75 74 20 77 68 61 74 20 VFS about what
d7a0: 74 68 65 20 68 69 67 68 65 72 20 6c 61 79 65 72 the higher layer
d7b0: 73 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 s of the SQLite
d7c0: 73 74 61 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e stack are doing.
d7d0: 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f .** This file co
d7e0: 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 62 79 ntrol is used by
d7f0: 20 73 6f 6d 65 20 56 46 53 20 61 63 74 69 76 69 some VFS activi
d800: 74 79 20 74 72 61 63 69 6e 67 20 5b 73 68 69 6d ty tracing [shim
d810: 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d s]..** The argum
d820: 65 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 ent is a zero-te
d830: 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 2e rminated string.
d840: 20 20 48 69 67 68 65 72 20 6c 61 79 65 72 73 20 Higher layers
d850: 69 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 in the.** SQLite
d860: 20 73 74 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 stack may gener
d870: 61 74 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 ate instances of
d880: 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 this file contr
d890: 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 ol if.** the [SQ
d8a0: 4c 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 LITE_USE_FCNTL_T
d8b0: 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 RACE] compile-ti
d8c0: 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 me option is ena
d8d0: 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e bled..**.** <li>
d8e0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 [[SQLITE_FCNTL_H
d8f0: 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 AS_MOVED]].** Th
d900: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
d910: 48 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20 HAS_MOVED] file
d920: 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 control interpre
d930: 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 ts its argument
d940: 61 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 as a.** pointer
d950: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e to an integer an
d960: 64 20 69 74 20 77 72 69 74 65 73 20 61 20 62 6f d it writes a bo
d970: 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61 74 20 olean into that
d980: 69 6e 74 65 67 65 72 20 64 65 70 65 6e 64 69 6e integer dependin
d990: 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 g.** on whether
d9a0: 6f 72 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 or not the file
d9b0: 68 61 73 20 62 65 65 6e 20 72 65 6e 61 6d 65 64 has been renamed
d9c0: 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65 , moved, or dele
d9d0: 74 65 64 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20 ted since it.**
d9e0: 77 61 73 20 66 69 72 73 74 20 6f 70 65 6e 65 64 was first opened
d9f0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
da00: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 LITE_FCNTL_WIN32
da10: 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a _SET_HANDLE]].**
da20: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e The [SQLITE_FCN
da30: 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e TL_WIN32_SET_HAN
da40: 44 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 DLE] opcode is u
da50: 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e sed for debuggin
da60: 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f g. This.** opco
da70: 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 de causes the xF
da80: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f ileControl metho
da90: 64 20 74 6f 20 73 77 61 70 20 74 68 65 20 66 69 d to swap the fi
daa0: 6c 65 20 68 61 6e 64 6c 65 20 77 69 74 68 20 74 le handle with t
dab0: 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 he one.** pointe
dac0: 64 20 74 6f 20 62 79 20 74 68 65 20 70 41 72 67 d to by the pArg
dad0: 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 69 73 argument. This
dae0: 20 63 61 70 61 62 69 6c 69 74 79 20 69 73 20 75 capability is u
daf0: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 sed during testi
db00: 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e ng.** and only n
db10: 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f eeds to be suppo
db20: 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 rted when SQLITE
db30: 5f 54 45 53 54 20 69 73 20 64 65 66 69 6e 65 64 _TEST is defined
db40: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
db50: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 LITE_FCNTL_WAL_B
db60: 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 LOCK]].** The [S
db70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f QLITE_FCNTL_WAL_
db80: 42 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69 67 6e BLOCK] is a sign
db90: 61 6c 20 74 6f 20 74 68 65 20 56 46 53 20 6c 61 al to the VFS la
dba0: 79 65 72 20 74 68 61 74 20 69 74 20 6d 69 67 68 yer that it migh
dbb0: 74 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74 61 67 t.** be advantag
dbc0: 65 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e eous to block on
dbd0: 20 74 68 65 20 6e 65 78 74 20 57 41 4c 20 6c 6f the next WAL lo
dbe0: 63 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b 20 69 ck if the lock i
dbf0: 73 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74 65 6c s not immediatel
dc00: 79 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65 2e 20 y.** available.
dc10: 20 54 68 65 20 57 41 4c 20 73 75 62 73 79 73 74 The WAL subsyst
dc20: 65 6d 20 69 73 73 75 65 73 20 74 68 69 73 20 73 em issues this s
dc30: 69 67 6e 61 6c 20 64 75 72 69 6e 67 20 72 61 72 ignal during rar
dc40: 65 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61 6e 63 e.** circumstanc
dc50: 65 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 es in order to f
dc60: 69 78 20 61 20 70 72 6f 62 6c 65 6d 20 77 69 74 ix a problem wit
dc70: 68 20 70 72 69 6f 72 69 74 79 20 69 6e 76 65 72 h priority inver
dc80: 73 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 sion..** Applica
dc90: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c 65 6d tions should <em
dca0: 3e 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20 74 68 >not</em> use th
dcb0: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e is file-control.
dcc0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
dcd0: 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 ITE_FCNTL_ZIPVFS
dce0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 ]].** The [SQLIT
dcf0: 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 20 E_FCNTL_ZIPVFS]
dd00: 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d opcode is implem
dd10: 65 6e 74 65 64 20 62 79 20 7a 69 70 76 66 73 20 ented by zipvfs
dd20: 6f 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65 72 0a only. All other.
dd30: 2a 2a 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 ** VFS should re
dd40: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 turn SQLITE_NOTF
dd50: 4f 55 4e 44 20 66 6f 72 20 74 68 69 73 20 6f 70 OUND for this op
dd60: 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e code..**.** <li>
dd70: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 [[SQLITE_FCNTL_R
dd80: 42 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c BU]].** The [SQL
dd90: 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 20 6f ITE_FCNTL_RBU] o
dda0: 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 pcode is impleme
ddb0: 6e 74 65 64 20 62 79 20 74 68 65 20 73 70 65 63 nted by the spec
ddc0: 69 61 6c 20 56 46 53 20 75 73 65 64 20 62 79 0a ial VFS used by.
ddd0: 2a 2a 20 74 68 65 20 52 42 55 20 65 78 74 65 6e ** the RBU exten
dde0: 73 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 sion only. All
ddf0: 6f 74 68 65 72 20 56 46 53 20 73 68 6f 75 6c 64 other VFS should
de00: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e return SQLITE_N
de10: 4f 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a 20 74 OTFOUND for.** t
de20: 68 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a his opcode. .**
de30: 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e </ul>.*/.#defin
de40: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c e SQLITE_FCNTL_L
de50: 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 OCKSTATE
de60: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 1.#define
de70: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 SQLITE_FCNTL_GE
de80: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 T_LOCKPROXYFILE
de90: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 2.#define
dea0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 SQLITE_FCNTL_SET
deb0: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 _LOCKPROXYFILE
dec0: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 3.#define S
ded0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 QLITE_FCNTL_LAST
dee0: 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 _ERRNO
def0: 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4.#define SQ
df00: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f LITE_FCNTL_SIZE_
df10: 48 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 HINT
df20: 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 5.#define SQL
df30: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f ITE_FCNTL_CHUNK_
df40: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 SIZE
df50: 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 6.#define SQLI
df60: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f TE_FCNTL_FILE_PO
df70: 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20 INTER
df80: 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 7.#define SQLIT
df90: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 E_FCNTL_SYNC_OMI
dfa0: 54 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20 TTED
dfb0: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 8.#define SQLITE
dfc0: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f _FCNTL_WIN32_AV_
dfd0: 52 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39 RETRY 9
dfe0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
dff0: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 FCNTL_PERSIST_WA
e000: 4c 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a L 10.
e010: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
e020: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 CNTL_OVERWRITE
e030: 20 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 11.#
e040: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
e050: 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 NTL_VFSNAME
e060: 20 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 12.#d
e070: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
e080: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 TL_POWERSAFE_OVE
e090: 52 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 RWRITE 13.#de
e0a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
e0b0: 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 L_PRAGMA
e0c0: 20 20 20 20 20 20 20 20 20 31 34 0a 23 64 65 66 14.#def
e0d0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
e0e0: 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20 _BUSYHANDLER
e0f0: 20 20 20 20 20 20 20 20 31 35 0a 23 64 65 66 69 15.#defi
e100: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
e110: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 TEMPFILENAME
e120: 20 20 20 20 20 20 20 31 36 0a 23 64 65 66 69 6e 16.#defin
e130: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d e SQLITE_FCNTL_M
e140: 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20 20 MAP_SIZE
e150: 20 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e 65 18.#define
e160: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 SQLITE_FCNTL_TR
e170: 41 43 45 20 20 20 20 20 20 20 20 20 20 20 20 20 ACE
e180: 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65 20 19.#define
e190: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 SQLITE_FCNTL_HAS
e1a0: 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20 20 _MOVED
e1b0: 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20 53 20.#define S
e1c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 QLITE_FCNTL_SYNC
e1d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
e1e0: 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53 51 21.#define SQ
e1f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 LITE_FCNTL_COMMI
e200: 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20 20 T_PHASETWO
e210: 20 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 22.#define SQL
e220: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f ITE_FCNTL_WIN32_
e230: 53 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 SET_HANDLE
e240: 20 32 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 23.#define SQLI
e250: 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f TE_FCNTL_WAL_BLO
e260: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 CK
e270: 32 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 24.#define SQLIT
e280: 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 20 20 E_FCNTL_ZIPVFS
e290: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 2
e2a0: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5.#define SQLITE
e2b0: 5f 46 43 4e 54 4c 5f 52 42 55 20 20 20 20 20 20 _FCNTL_RBU
e2c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 36 26
e2d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
e2e0: 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 FCNTL_VFS_POINTE
e2f0: 52 20 20 20 20 20 20 20 20 20 20 20 20 32 37 0a R 27.
e300: 0a 2f 2a 20 64 65 70 72 65 63 61 74 65 64 20 6e ./* deprecated n
e310: 61 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ames */.#define
e320: 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 SQLITE_GET_LOCKP
e330: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 ROXYFILE SQ
e340: 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c LITE_FCNTL_GET_L
e350: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 OCKPROXYFILE.#de
e360: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f fine SQLITE_SET_
e370: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 LOCKPROXYFILE
e380: 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f SQLITE_FCNTL_
e390: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c SET_LOCKPROXYFIL
e3a0: 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 E.#define SQLITE
e3b0: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 _LAST_ERRNO
e3c0: 20 20 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 SQLITE_F
e3d0: 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a CNTL_LAST_ERRNO.
e3e0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
e3f0: 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a : Mutex Handle.*
e400: 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d *.** The mutex m
e410: 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c odule within SQL
e420: 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c ite defines [sql
e430: 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 ite3_mutex] to b
e440: 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 e an.** abstract
e450: 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 type for a mute
e460: 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 x object. The S
e470: 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 QLite core never
e480: 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 looks.** at the
e490: 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 internal repres
e4a0: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b entation of an [
e4b0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 sqlite3_mutex].
e4c0: 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c It only.** deal
e4d0: 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 s with pointers
e4e0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
e4f0: 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a mutex] object..*
e500: 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 *.** Mutexes are
e510: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b created using [
e520: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c sqlite3_mutex_al
e530: 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 loc()]..*/.typed
e540: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
e550: 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 3_mutex sqlite3_
e560: 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 mutex;../*.** CA
e570: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 PI3REF: OS Inter
e580: 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a face Object.**.*
e590: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 * An instance of
e5a0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 the sqlite3_vfs
e5b0: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 object defines
e5c0: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 the interface be
e5d0: 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c tween.** the SQL
e5e0: 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 ite core and the
e5f0: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 underlying oper
e600: 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 ating system. T
e610: 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 he "vfs".** in t
e620: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f he name of the o
e630: 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 bject stands for
e640: 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 "virtual file s
e650: 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 ystem". See.**
e660: 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 the [VFS | VFS d
e670: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f ocumentation] fo
e680: 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d r further inform
e690: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ation..**.** The
e6a0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 value of the iV
e6b0: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 ersion field is
e6c0: 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 initially 1 but
e6d0: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e may be larger in
e6e0: 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 .** future versi
e6f0: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 ons of SQLite.
e700: 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 Additional field
e710: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 s may be appende
e720: 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a d to this.** obj
e730: 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 ect when the iVe
e740: 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 rsion value is i
e750: 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 ncreased. Note
e760: 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 that the structu
e770: 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c re.** of the sql
e780: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 ite3_vfs object
e790: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 changes in the t
e7a0: 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 ransaction betwe
e7b0: 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 en.** SQLite ver
e7c0: 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 sion 3.5.9 and 3
e7d0: 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 .6.0 and yet the
e7e0: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 iVersion field
e7f0: 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 was not.** modif
e800: 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ied..**.** The s
e810: 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 zOsFile field is
e820: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 the size of the
e830: 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c subclassed [sql
e840: 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 ite3_file].** st
e850: 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 ructure used by
e860: 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 this VFS. mxPat
e870: 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 hname is the max
e880: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a imum length of.*
e890: 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 * a pathname in
e8a0: 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 this VFS..**.**
e8b0: 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 Registered sqlit
e8c0: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 e3_vfs objects a
e8d0: 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e re kept on a lin
e8e0: 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 ked list formed
e8f0: 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 by.** the pNext
e900: 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 pointer. The [s
e910: 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 qlite3_vfs_regis
e920: 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 ter()].** and [s
e930: 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 qlite3_vfs_unreg
e940: 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 ister()] interfa
e950: 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 ces manage this
e960: 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 list.** in a thr
e970: 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 ead-safe way. T
e980: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f he [sqlite3_vfs_
e990: 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 find()] interfac
e9a0: 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 e.** searches th
e9b0: 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 e list. Neither
e9c0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
e9d0: 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 code nor the VF
e9e0: 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 S.** implementat
e9f0: 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 ion should use t
ea00: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 he pNext pointer
ea10: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 ..**.** The pNex
ea20: 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f t field is the o
ea30: 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 nly field in the
ea40: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 sqlite3_vfs.**
ea50: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 structure that S
ea60: 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 QLite will ever
ea70: 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 modify. SQLite
ea80: 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 will only access
ea90: 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 .** or modify th
eaa0: 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 is field while h
eab0: 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 olding a particu
eac0: 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 lar static mutex
ead0: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 ..** The applica
eae0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 tion should neve
eaf0: 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e r modify anythin
eb00: 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c g within the sql
eb10: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 ite3_vfs.** obje
eb20: 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 ct once the obje
eb30: 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 ct has been regi
eb40: 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 stered..**.** Th
eb50: 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f e zName field ho
eb60: 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 lds the name of
eb70: 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 the VFS module.
eb80: 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a The name must.*
eb90: 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f * be unique acro
eba0: 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c ss all VFS modul
ebb0: 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 es..**.** [[sqli
ebc0: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a te3_vfs.xOpen]].
ebd0: 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 ** ^SQLite guara
ebe0: 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a ntees that the z
ebf0: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 Filename paramet
ec00: 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 er to xOpen.** i
ec10: 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 s either a NULL
ec20: 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e pointer or strin
ec30: 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 g obtained.** fr
ec40: 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 om xFullPathname
ec50: 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f () with an optio
ec60: 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 nal suffix added
ec70: 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 ..** ^If a suffi
ec80: 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 x is added to th
ec90: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 e zFilename para
eca0: 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a meter, it will.*
ecb0: 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 * consist of a s
ecc0: 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 ingle "-" charac
ecd0: 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 ter followed by
ece0: 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 no more than.**
ecf0: 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 11 alphanumeric
ed00: 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 and/or "-" chara
ed10: 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 cters..** ^SQLit
ed20: 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e e further guaran
ed30: 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 tees that.** the
ed40: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 string will be
ed50: 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e valid and unchan
ed60: 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 ged until xClose
ed70: 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e () is.** called.
ed80: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 Because of the
ed90: 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 previous sentenc
eda0: 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 e,.** the [sqlit
edb0: 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 e3_file] can saf
edc0: 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e ely store a poin
edd0: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 ter to the.** fi
ede0: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 lename if it nee
edf0: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 ds to remember t
ee00: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 he filename for
ee10: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 some reason..**
ee20: 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 If the zFilename
ee30: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f parameter to xO
ee40: 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f pen is a NULL po
ee50: 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e inter then xOpen
ee60: 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 .** must invent
ee70: 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 its own temporar
ee80: 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 y name for the f
ee90: 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 ile. ^Whenever
eea0: 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d the .** xFilenam
eeb0: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e e parameter is N
eec0: 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f ULL it will also
eed0: 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 be the case tha
eee0: 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 t the.** flags p
eef0: 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e arameter will in
ef00: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 clude [SQLITE_OP
ef10: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 EN_DELETEONCLOSE
ef20: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 ]..**.** The fla
ef30: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 gs argument to x
ef40: 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 Open() includes
ef50: 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a all bits set in.
ef60: 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 ** the flags arg
ef70: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 ument to [sqlite
ef80: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 3_open_v2()]. O
ef90: 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 r if [sqlite3_op
efa0: 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c en()].** or [sql
efb0: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 ite3_open16()] i
efc0: 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 s used, then fla
efd0: 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c gs includes at l
efe0: 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f east.** [SQLITE_
eff0: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 OPEN_READWRITE]
f000: 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 | [SQLITE_OPEN_C
f010: 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 REATE]. .** If x
f020: 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 Open() opens a f
f030: 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 ile read-only th
f040: 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 en it sets *pOut
f050: 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c Flags to.** incl
f060: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e ude [SQLITE_OPEN
f070: 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 _READONLY]. Oth
f080: 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 er bits in *pOut
f090: 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 Flags may be set
f0a0: 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 ..**.** ^(SQLite
f0b0: 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f will also add o
f0c0: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 ne of the follow
f0d0: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 ing flags to the
f0e0: 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c xOpen().** call
f0f0: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 , depending on t
f100: 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 he object being
f110: 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 opened:.**.** <u
f120: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c l>.** <li> [SQL
f130: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 ITE_OPEN_MAIN_DB
f140: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 ].** <li> [SQLI
f150: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 TE_OPEN_MAIN_JOU
f160: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b RNAL].** <li> [
f170: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 SQLITE_OPEN_TEMP
f180: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 _DB].** <li> [S
f190: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f QLITE_OPEN_TEMP_
f1a0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e JOURNAL].** <li>
f1b0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 [SQLITE_OPEN_T
f1c0: 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 RANSIENT_DB].**
f1d0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
f1e0: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a EN_SUBJOURNAL].*
f1f0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f * <li> [SQLITE_
f200: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 OPEN_MASTER_JOUR
f210: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 NAL].** <li> [S
f220: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a QLITE_OPEN_WAL].
f230: 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a ** </ul>)^.**.**
f240: 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d The file I/O im
f250: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e plementation can
f260: 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 use the object
f270: 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a type flags to.**
f280: 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 change the way
f290: 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 it deals with fi
f2a0: 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c les. For exampl
f2b0: 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f e, an applicatio
f2c0: 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e n.** that does n
f2d0: 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 ot care about cr
f2e0: 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 ash recovery or
f2f0: 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d rollback might m
f300: 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 ake.** the open
f310: 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c of a journal fil
f320: 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 e a no-op. Writ
f330: 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e es to this journ
f340: 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f al would.** also
f350: 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 be no-ops, and
f360: 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 any attempt to r
f370: 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 ead the journal
f380: 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 would return.**
f390: 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f SQLITE_IOERR. O
f3a0: 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 r the implementa
f3b0: 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 tion might recog
f3c0: 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 nize that a data
f3d0: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c base.** file wil
f3e0: 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d l be doing page-
f3f0: 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 aligned sector r
f400: 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 eads and writes
f410: 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f in a random.** o
f420: 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 rder and set up
f430: 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 its I/O subsyste
f440: 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a m accordingly..*
f450: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 *.** SQLite migh
f460: 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f t also add one o
f470: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 f the following
f480: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 flags to the xOp
f490: 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a en method:.**.**
f4a0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 <ul>.** <li> [S
f4b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 QLITE_OPEN_DELET
f4c0: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 EONCLOSE].** <li
f4d0: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 > [SQLITE_OPEN_E
f4e0: 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 XCLUSIVE].** </u
f4f0: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 l>.**.** The [SQ
f500: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 LITE_OPEN_DELETE
f510: 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 ONCLOSE] flag me
f520: 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f ans the file sho
f530: 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 uld be.** delete
f540: 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f d when it is clo
f550: 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 sed. ^The [SQLI
f560: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e TE_OPEN_DELETEON
f570: 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 CLOSE].** will b
f580: 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 e set for TEMP d
f590: 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 atabases and the
f5a0: 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 ir journals, tra
f5b0: 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 nsient.** databa
f5c0: 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 ses, and subjour
f5d0: 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 nals..**.** ^The
f5e0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 [SQLITE_OPEN_EX
f5f0: 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 CLUSIVE] flag is
f600: 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 always used in
f610: 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 conjunction.** w
f620: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ith the [SQLITE_
f630: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 OPEN_CREATE] fla
f640: 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 g, which are bot
f650: 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e h directly.** an
f660: 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f alogous to the O
f670: 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 _EXCL and O_CREA
f680: 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 T flags of the P
f690: 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 OSIX open().** A
f6a0: 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f PI. The SQLITE_
f6b0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 OPEN_EXCLUSIVE f
f6c0: 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 lag, when paired
f6d0: 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 with the .** SQ
f6e0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 LITE_OPEN_CREATE
f6f0: 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 , is used to ind
f700: 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 icate that file
f710: 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a should always.**
f720: 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 be created, and
f730: 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 that it is an e
f740: 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 rror if it alrea
f750: 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 dy exists..** It
f760: 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 is <i>not</i> u
f770: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 sed to indicate
f780: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 the file should
f790: 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f be opened .** fo
f7a0: 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 r exclusive acce
f7b0: 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 ss..**.** ^At le
f7c0: 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 ast szOsFile byt
f7d0: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 es of memory are
f7e0: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 allocated by SQ
f7f0: 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 Lite.** to hold
f800: 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 the [sqlite3_fi
f810: 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 le] structure pa
f820: 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 ssed as the thir
f830: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f d.** argument to
f840: 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 xOpen. The xOp
f850: 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e en method does n
f860: 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c ot have to.** al
f870: 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 locate the struc
f880: 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 ture; it should
f890: 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e just fill it in.
f8a0: 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 Note that.** t
f8b0: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 he xOpen method
f8c0: 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c must set the sql
f8d0: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f ite3_file.pMetho
f8e0: 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 ds to either.**
f8f0: 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 a valid [sqlite3
f900: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a _io_methods] obj
f910: 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 ect or to NULL.
f920: 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a xOpen must do.*
f930: 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 * this even if t
f940: 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 he open fails.
f950: 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 SQLite expects t
f960: 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f hat the sqlite3_
f970: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a file.pMethods.**
f980: 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 element will be
f990: 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 valid after xOp
f9a0: 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 en returns regar
f9b0: 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 dless of the suc
f9c0: 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 cess.** or failu
f9d0: 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 re of the xOpen
f9e0: 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 call..**.** [[sq
f9f0: 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 lite3_vfs.xAcces
fa00: 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 s]].** ^The flag
fa10: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 s argument to xA
fa20: 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b ccess() may be [
fa30: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 SQLITE_ACCESS_EX
fa40: 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 ISTS].** to test
fa50: 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e for the existen
fa60: 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 ce of a file, or
fa70: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f [SQLITE_ACCESS_
fa80: 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a READWRITE] to.**
fa90: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 test whether a
faa0: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 file is readable
fab0: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f and writable, o
fac0: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 r [SQLITE_ACCESS
fad0: 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 _READ].** to tes
fae0: 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 t whether a file
faf0: 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 is at least rea
fb00: 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c dable. The fil
fb10: 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 e can be a.** di
fb20: 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e rectory..**.** ^
fb30: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 SQLite will alwa
fb40: 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c ys allocate at l
fb50: 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b east mxPathname+
fb60: 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 1 bytes for the.
fb70: 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 ** output buffer
fb80: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 xFullPathname.
fb90: 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 The exact size
fba0: 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 of the output bu
fbb0: 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 ffer.** is also
fbc0: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 passed as a para
fbd0: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d meter to both m
fbe0: 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f ethods. If the o
fbf0: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 utput buffer.**
fc00: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f is not large eno
fc10: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e ugh, [SQLITE_CAN
fc20: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 TOPEN] should be
fc30: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 returned. Since
fc40: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 this is.** hand
fc50: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 led as a fatal e
fc60: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 rror by SQLite,
fc70: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 vfs implementati
fc80: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 ons should endea
fc90: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e vor.** to preven
fca0: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e t this by settin
fcb0: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 g mxPathname to
fcc0: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c a sufficiently l
fcd0: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a arge value..**.*
fce0: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 * The xRandomnes
fcf0: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 s(), xSleep(), x
fd00: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 CurrentTime(), a
fd10: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 nd xCurrentTimeI
fd20: 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 nt64().** interf
fd30: 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 aces are not str
fd40: 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 ictly a part of
fd50: 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 the filesystem,
fd60: 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 but they are.**
fd70: 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 included in the
fd80: 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f VFS structure fo
fd90: 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a r completeness..
fda0: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 ** The xRandomne
fdb0: 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 ss() function at
fdc0: 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e tempts to return
fdd0: 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a nBytes bytes.**
fde0: 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 of good-quality
fdf0: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f randomness into
fe00: 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 zOut. The retu
fe10: 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 rn value is.** t
fe20: 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 he actual number
fe30: 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e of bytes of ran
fe40: 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 domness obtained
fe50: 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 ..** The xSleep(
fe60: 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 ) method causes
fe70: 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 the calling thre
fe80: 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 ad to sleep for
fe90: 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 at.** least the
fea0: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 number of micros
feb0: 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e econds given. ^
fec0: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 The xCurrentTime
fed0: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 ().** method ret
fee0: 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 urns a Julian Da
fef0: 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 y Number for the
ff00: 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e current date an
ff10: 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 d time as.** a f
ff20: 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 loating point va
ff30: 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 lue..** ^The xCu
ff40: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 rrentTimeInt64()
ff50: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c method returns,
ff60: 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 as an integer,
ff70: 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 the Julian.** Da
ff80: 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c y Number multipl
ff90: 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20 ied by 86400000
ffa0: 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d (the number of m
ffb0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a illiseconds in .
ffc0: 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 ** a 24-hour day
ffd0: 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 ). .** ^SQLite
ffe0: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 will use the xCu
fff0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 rrentTimeInt64()
10000 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 method to get t
10010 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 he current.** da
10020 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 te and time if t
10030 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 hat method is av
10040 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 ailable (if iVer
10050 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a sion is 2 or .**
10060 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 greater and the
10070 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 function pointe
10080 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 r is not NULL) a
10090 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 nd will fall bac
100a0 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 k.** to xCurrent
100b0 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 Time() if xCurre
100c0 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 ntTimeInt64() is
100d0 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a unavailable..**
100e0 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 .** ^The xSetSys
100f0 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 temCall(), xGetS
10100 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 ystemCall(), and
10110 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c xNestSystemCall
10120 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a () interfaces.**
10130 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 are not used by
10140 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 the SQLite core
10150 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 . These optiona
10160 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 l interfaces are
10170 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 provided.** by
10180 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 some VFSes to fa
10190 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 cilitate testing
101a0 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 of the VFS code
101b0 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 . By overriding
101c0 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 .** system calls
101d0 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 with functions
101e0 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f under its contro
101f0 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 l, a test progra
10200 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 m can.** simulat
10210 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 e faults and err
10220 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 or conditions th
10230 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 at would otherwi
10240 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a se be difficult.
10250 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 ** or impossible
10260 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 to induce. The
10270 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 set of system c
10280 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 alls that can be
10290 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 overridden.** v
102a0 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 aries from one V
102b0 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 FS to another, a
102c0 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 nd from one vers
102d0 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 ion of the same
102e0 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 VFS to the.** ne
102f0 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e xt. Application
10300 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65 s that use these
10310 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 interfaces must
10320 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 be prepared for
10330 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f any.** or all o
10340 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 f these interfac
10350 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 es to be NULL or
10360 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 for their behav
10370 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a ior to change.**
10380 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 from one releas
10390 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 e to the next.
103a0 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 Applications mus
103b0 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f t not attempt to
103c0 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f access.** any o
103d0 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 f these methods
103e0 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 if the iVersion
103f0 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 of the VFS is le
10400 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 ss than 3..*/.ty
10410 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
10420 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 ite3_vfs sqlite3
10430 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f _vfs;.typedef vo
10440 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 id (*sqlite3_sys
10450 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b call_ptr)(void);
10460 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f .struct sqlite3_
10470 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 vfs {. int iVer
10480 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 sion;
10490 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 /* Structure ve
104a0 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 rsion number (cu
104b0 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 rrently 3) */.
104c0 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 int szOsFile;
104d0 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 /* Size
104e0 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 of subclassed s
104f0 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 qlite3_file */.
10500 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b int mxPathname;
10510 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 /* Max
10520 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 imum file pathna
10530 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 me length */. s
10540 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 qlite3_vfs *pNex
10550 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 t; /* Next
10560 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a registered VFS *
10570 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
10580 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 zName; /*
10590 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 Name of this vir
105a0 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d tual file system
105b0 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 */. void *pApp
105c0 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f Data; /
105d0 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 * Pointer to app
105e0 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 lication-specifi
105f0 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 c data */. int
10600 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 (*xOpen)(sqlite3
10610 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 _vfs*, const cha
10620 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 r *zName, sqlite
10630 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 3_file*,.
10640 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 int flag
10650 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 s, int *pOutFlag
10660 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c s);. int (*xDel
10670 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ete)(sqlite3_vfs
10680 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
10690 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 Name, int syncDi
106a0 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 r);. int (*xAcc
106b0 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ess)(sqlite3_vfs
106c0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
106d0 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c Name, int flags,
106e0 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a int *pResOut);.
106f0 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 int (*xFullPat
10700 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 hname)(sqlite3_v
10710 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 fs*, const char
10720 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 *zName, int nOut
10730 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 , char *zOut);.
10740 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e void *(*xDlOpen
10750 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
10760 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c const char *zFil
10770 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 ename);. void (
10780 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 *xDlError)(sqlit
10790 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 e3_vfs*, int nBy
107a0 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 te, char *zErrMs
107b0 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 g);. void (*(*x
107c0 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 DlSym)(sqlite3_v
107d0 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 fs*,void*, const
107e0 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 char *zSymbol))
107f0 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 (void);. void (
10800 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 *xDlClose)(sqlit
10810 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b e3_vfs*, void*);
10820 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d . int (*xRandom
10830 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 ness)(sqlite3_vf
10840 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 s*, int nByte, c
10850 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e har *zOut);. in
10860 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 t (*xSleep)(sqli
10870 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 te3_vfs*, int mi
10880 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 croseconds);. i
10890 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d nt (*xCurrentTim
108a0 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c e)(sqlite3_vfs*,
108b0 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 double*);. int
108c0 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 (*xGetLastError
108d0 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
108e0 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 int, char *);.
108f0 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 /*. ** The meth
10900 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e ods above are in
10910 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 version 1 of th
10920 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a e sqlite_vfs obj
10930 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 ect. ** definit
10940 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 ion. Those that
10950 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 follow are adde
10960 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f d in version 2 o
10970 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 r later. */. i
10980 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d nt (*xCurrentTim
10990 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f eInt64)(sqlite3_
109a0 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e vfs*, sqlite3_in
109b0 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a t64*);. /*. **
109c0 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f The methods abo
109d0 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f ve are in versio
109e0 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 ns 1 and 2 of th
109f0 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a e sqlite_vfs obj
10a00 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 ect.. ** Those
10a10 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 below are for ve
10a20 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 rsion 3 and grea
10a30 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 ter.. */. int
10a40 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c (*xSetSystemCall
10a50 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
10a60 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
10a70 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 e, sqlite3_sysca
10a80 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 ll_ptr);. sqlit
10a90 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 e3_syscall_ptr (
10aa0 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 *xGetSystemCall)
10ab0 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 (sqlite3_vfs*, c
10ac0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
10ad0 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 );. const char
10ae0 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 *(*xNextSystemCa
10af0 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a ll)(sqlite3_vfs*
10b00 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
10b10 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 ame);. /*. **
10b20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 The methods abov
10b30 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e e are in version
10b40 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 s 1 through 3 of
10b50 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 the sqlite_vfs
10b60 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 object.. ** New
10b70 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 fields may be a
10b80 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 ppended in figur
10b90 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 e versions. The
10ba0 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 iVersion. ** v
10bb0 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d alue will increm
10bc0 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 ent whenever thi
10bd0 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f s happens. . */
10be0 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .};../*.** CAPI3
10bf0 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 REF: Flags for t
10c00 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d he xAccess VFS m
10c10 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ethod.**.** Thes
10c20 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 e integer consta
10c30 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 nts can be used
10c40 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 as the third par
10c50 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 ameter to.** the
10c60 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 xAccess method
10c70 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 of an [sqlite3_v
10c80 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 fs] object. The
10c90 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 y determine.** w
10ca0 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d hat kind of perm
10cb0 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 issions the xAcc
10cc0 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f ess method is lo
10cd0 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 oking for..** Wi
10ce0 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 th SQLITE_ACCESS
10cf0 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 _EXISTS, the xAc
10d00 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 cess method.** s
10d10 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 imply checks whe
10d20 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 ther the file ex
10d30 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 ists..** With SQ
10d40 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 LITE_ACCESS_READ
10d50 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 WRITE, the xAcce
10d60 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 ss method.** che
10d70 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 cks whether the
10d80 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 named directory
10d90 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 is both readable
10da0 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a and writable.**
10db0 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 (in other words
10dc0 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 , if files can b
10dd0 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 e added, removed
10de0 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 , and renamed wi
10df0 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 thin.** the dire
10e00 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 ctory)..** The S
10e10 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 QLITE_ACCESS_REA
10e20 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 DWRITE constant
10e30 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 is currently use
10e40 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a d only by the.**
10e50 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 [temp_store_dir
10e60 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 ectory pragma],
10e70 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c though this coul
10e80 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 d change in a fu
10e90 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 ture.** release
10ea0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 of SQLite..** Wi
10eb0 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 th SQLITE_ACCESS
10ec0 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 _READ, the xAcce
10ed0 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 ss method.** che
10ee0 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 cks whether the
10ef0 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 file is readable
10f00 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 . The SQLITE_AC
10f10 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 CESS_READ consta
10f20 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 nt is.** current
10f30 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 ly unused, thoug
10f40 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 h it might be us
10f50 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 ed in a future r
10f60 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c elease of.** SQL
10f70 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ite..*/.#define
10f80 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 SQLITE_ACCESS_EX
10f90 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e ISTS 0.#defin
10fa0 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f e SQLITE_ACCESS_
10fb0 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a READWRITE 1 /*
10fc0 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 Used by PRAGMA
10fd0 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 temp_store_direc
10fe0 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 tory */.#define
10ff0 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 SQLITE_ACCESS_RE
11000 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 AD 2 /* U
11010 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 nused */../*.**
11020 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 CAPI3REF: Flags
11030 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b for the xShmLock
11040 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a VFS method.**.*
11050 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 * These integer
11060 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 constants define
11070 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 the various loc
11080 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a king operations.
11090 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 ** allowed by th
110a0 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f e xShmLock metho
110b0 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f d of [sqlite3_io
110c0 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a _methods]. The.
110d0 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 ** following are
110e0 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 the only legal
110f0 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 combinations of
11100 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 flags to the.**
11110 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a xShmLock method:
11120 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c .**.** <ul>.** <
11130 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f li> SQLITE_SHM_
11140 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 LOCK | SQLITE_SH
11150 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e M_SHARED.** <li>
11160 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 SQLITE_SHM_LOC
11170 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 K | SQLITE_SHM_E
11180 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e XCLUSIVE.** <li>
11190 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c SQLITE_SHM_UNL
111a0 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d OCK | SQLITE_SHM
111b0 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 _SHARED.** <li>
111c0 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f SQLITE_SHM_UNLO
111d0 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f CK | SQLITE_SHM_
111e0 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 EXCLUSIVE.** </u
111f0 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e l>.**.** When un
11200 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d locking, the sam
11210 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c e SHARED or EXCL
11220 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 USIVE flag must
11230 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a be supplied as.*
11240 2a 20 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74 * was given on t
11250 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 he corresponding
11260 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 lock. .**.** T
11270 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 he xShmLock meth
11280 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f od can transitio
11290 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b n between unlock
112a0 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 ed and SHARED or
112b0 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f .** between unlo
112c0 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 cked and EXCLUSI
112d0 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 VE. It cannot t
112e0 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 ransition betwee
112f0 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 n SHARED.** and
11300 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 EXCLUSIVE..*/.#d
11310 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d efine SQLITE_SHM
11320 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a _UNLOCK 1.
11330 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
11340 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 HM_LOCK
11350 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
11360 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 _SHM_SHARED
11370 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 4.#define SQLI
11380 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 TE_SHM_EXCLUSIVE
11390 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 8../*.** CAP
113a0 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 I3REF: Maximum x
113b0 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a ShmLock index.**
113c0 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b .** The xShmLock
113d0 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 method on [sqli
113e0 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 te3_io_methods]
113f0 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a may use values.*
11400 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 * between 0 and
11410 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 this upper bound
11420 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 as its "offset"
11430 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 argument..** Th
11440 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 e SQLite core wi
11450 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 ll never attempt
11460 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 to acquire or r
11470 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b elease a.** lock
11480 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 outside of this
11490 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e range.*/.#defin
114a0 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f e SQLITE_SHM_NLO
114b0 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a CK 8.../*
114c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e .** CAPI3REF: In
114d0 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c itialize The SQL
114e0 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a ite Library.**.*
114f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 * ^The sqlite3_i
11500 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 nitialize() rout
11510 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 ine initializes
11520 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 the.** SQLite li
11530 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c brary. ^The sql
11540 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 ite3_shutdown()
11550 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c routine.** deall
11560 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 ocates any resou
11570 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61 rces that were a
11580 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 llocated by sqli
11590 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
115a0 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 ..** These routi
115b0 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 nes are designed
115c0 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 to aid in proce
115d0 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f ss initializatio
115e0 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 n and.** shutdow
115f0 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 n on embedded sy
11600 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 stems. Workstat
11610 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 ion applications
11620 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 using.** SQLite
11630 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 normally do not
11640 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 need to invoke
11650 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 either of these
11660 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 routines..**.**
11670 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 A call to sqlite
11680 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 3_initialize() i
11690 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 s an "effective"
116a0 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a call if it is.*
116b0 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 * the first time
116c0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
116d0 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 ize() is invoked
116e0 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 during the life
116f0 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 time of.** the p
11700 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 rocess, or if it
11710 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69 is the first ti
11720 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 me sqlite3_initi
11730 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b alize() is invok
11740 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 ed.** following
11750 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 a call to sqlite
11760 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 3_shutdown(). ^
11770 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 (Only an effecti
11780 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 ve call.** of sq
11790 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
117a0 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 () does any init
117b0 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c ialization. All
117c0 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 other calls.**
117d0 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d are harmless no-
117e0 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 ops.)^.**.** A c
117f0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 all to sqlite3_s
11800 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 hutdown() is an
11810 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c "effective" call
11820 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 if it is the fi
11830 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 rst.** call to s
11840 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
11850 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 ) since the last
11860 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
11870 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a ize(). ^(Only.*
11880 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 * an effective c
11890 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 all to sqlite3_s
118a0 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 hutdown() does a
118b0 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 ny deinitializat
118c0 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 ion..** All othe
118d0 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f r valid calls to
118e0 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
118f0 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 n() are harmless
11900 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a no-ops.)^.**.**
11910 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 The sqlite3_ini
11920 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 tialize() interf
11930 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66 ace is threadsaf
11940 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 e, but sqlite3_s
11950 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 hutdown().** is
11960 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 not. The sqlite
11970 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 3_shutdown() int
11980 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 erface must only
11990 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 be called from
119a0 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 a.** single thre
119b0 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 ad. All open [d
119c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
119d0 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f ons] must be clo
119e0 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f sed and all.** o
119f0 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f ther SQLite reso
11a00 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 urces must be de
11a10 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 allocated prior
11a20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 to invoking.** s
11a30 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
11a40 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f )..**.** Among o
11a50 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 ther things, ^sq
11a60 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
11a70 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a () will invoke.*
11a80 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 * sqlite3_os_ini
11a90 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c t(). Similarly,
11aa0 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f ^sqlite3_shutdo
11ab0 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 wn().** will inv
11ac0 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 oke sqlite3_os_e
11ad0 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 nd()..**.** ^The
11ae0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
11af0 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 ize() routine re
11b00 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b turns [SQLITE_OK
11b10 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a ] on success..**
11b20 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 ^If for some re
11b30 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e ason, sqlite3_in
11b40 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e itialize() is un
11b50 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 able to initiali
11b60 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 ze.** the librar
11b70 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73 y (perhaps it is
11b80 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 unable to alloc
11b90 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 ate a needed res
11ba0 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 ource such.** as
11bb0 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 a mutex) it ret
11bc0 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 urns an [error c
11bd0 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 ode] other than
11be0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a [SQLITE_OK]..**.
11bf0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
11c00 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 initialize() rou
11c10 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 tine is called i
11c20 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e nternally by man
11c30 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 y other.** SQLit
11c40 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 e interfaces so
11c50 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 that an applicat
11c60 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 ion usually does
11c70 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 not need to.**
11c80 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 invoke sqlite3_i
11c90 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 nitialize() dire
11ca0 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 ctly. For examp
11cb0 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 le, [sqlite3_ope
11cc0 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 n()].** calls sq
11cd0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
11ce0 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 () so the SQLite
11cf0 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 library will be
11d00 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a automatically.*
11d10 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 * initialized wh
11d20 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e en [sqlite3_open
11d30 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 ()] is called if
11d40 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 it has not be i
11d50 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c nitialized.** al
11d60 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 ready. ^However
11d70 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 , if SQLite is c
11d80 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 ompiled with the
11d90 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 [SQLITE_OMIT_AU
11da0 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 TOINIT].** compi
11db0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 le-time option,
11dc0 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 then the automat
11dd0 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 ic calls to sqli
11de0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
11df0 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 .** are omitted
11e00 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 and the applicat
11e10 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 ion must call sq
11e20 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
11e30 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 () directly.** p
11e40 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e rior to using an
11e50 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 y other SQLite i
11e60 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d nterface. For m
11e70 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 aximum portabili
11e80 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 ty,.** it is rec
11e90 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 ommended that ap
11ea0 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 plications alway
11eb0 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 s invoke sqlite3
11ec0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a _initialize().**
11ed0 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 directly prior
11ee0 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 to using any oth
11ef0 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 er SQLite interf
11f00 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c ace. Future rel
11f10 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 eases.** of SQLi
11f20 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 te may require t
11f30 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 his. In other w
11f40 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 ords, the behavi
11f50 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 or exhibited.**
11f60 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 when SQLite is c
11f70 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 ompiled with [SQ
11f80 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e LITE_OMIT_AUTOIN
11f90 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 IT] might become
11fa0 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 the.** default
11fb0 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 behavior in some
11fc0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 future release
11fd0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a of SQLite..**.**
11fe0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f The sqlite3_os_
11ff0 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 init() routine d
12000 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 oes operating-sy
12010 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a stem specific.**
12020 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 initialization
12030 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 of the SQLite li
12040 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 brary. The sqli
12050 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 te3_os_end().**
12060 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 routine undoes t
12070 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c he effect of sql
12080 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 ite3_os_init().
12090 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a Typical tasks.*
120a0 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 * performed by t
120b0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e hese routines in
120c0 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e clude allocation
120d0 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e or deallocation
120e0 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 .** of static re
120f0 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c sources, initial
12100 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 ization of globa
12110 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 l variables,.**
12120 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 setting up a def
12130 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 ault [sqlite3_vf
12140 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 s] module, or se
12150 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 tting up.** a de
12160 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 fault configurat
12170 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ion using [sqlit
12180 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a e3_config()]..**
12190 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
121a0 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 ion should never
121b0 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 invoke either s
121c0 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
121d0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f .** or sqlite3_o
121e0 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 s_end() directly
121f0 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 . The applicati
12200 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 on should only i
12210 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 nvoke.** sqlite3
12220 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e _initialize() an
12230 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f d sqlite3_shutdo
12240 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 wn(). The sqlit
12250 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 e3_os_init().**
12260 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c interface is cal
12270 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c led automaticall
12280 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 y by sqlite3_ini
12290 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a tialize() and.**
122a0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 sqlite3_os_end(
122b0 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 ) is called by s
122c0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
122d0 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a ). Appropriate.
122e0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
122f0 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f ns for sqlite3_o
12300 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c s_init() and sql
12310 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a ite3_os_end().**
12320 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 are built into
12330 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 SQLite when it i
12340 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 s compiled for U
12350 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 nix, Windows, or
12360 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b OS/2..** When [
12370 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 custom builds |
12380 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 built for other
12390 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 platforms].** (u
123a0 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 sing the [SQLITE
123b0 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d _OS_OTHER=1] com
123c0 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 pile-time.** opt
123d0 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 ion) the applica
123e0 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 tion must supply
123f0 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c a suitable impl
12400 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a ementation for.*
12410 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 * sqlite3_os_ini
12420 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f t() and sqlite3_
12430 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 os_end(). An ap
12440 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 plication-suppli
12450 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 ed.** implementa
12460 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f tion of sqlite3_
12470 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c os_init() or sql
12480 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a ite3_os_end().**
12490 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 must return [SQ
124a0 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 LITE_OK] on succ
124b0 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 ess and some oth
124c0 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 er [error code]
124d0 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e upon.** failure.
124e0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
124f0 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c nt SQLITE_STDCAL
12500 4c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 L sqlite3_initia
12510 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49 lize(void);.SQLI
12520 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
12530 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
12540 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3_shutdown(void)
12550 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
12560 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
12570 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
12580 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 void);.SQLITE_AP
12590 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
125a0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 73 5f CALL sqlite3_os_
125b0 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a end(void);../*.*
125c0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 * CAPI3REF: Conf
125d0 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 iguring The SQLi
125e0 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a te Library.**.**
125f0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e The sqlite3_con
12600 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 fig() interface
12610 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 is used to make
12620 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 global configura
12630 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 tion.** changes
12640 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 to SQLite in ord
12650 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 er to tune SQLit
12660 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 e to the specifi
12670 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 c needs of.** th
12680 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 e application.
12690 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 The default conf
126a0 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 iguration is rec
126b0 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 ommended for mos
126c0 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e t.** application
126d0 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f s and so this ro
126e0 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 utine is usually
126f0 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 not necessary.
12700 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 It is.** provid
12710 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 ed to support ra
12720 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 re applications
12730 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 with unusual nee
12740 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 ds..**.** <b>The
12750 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
12760 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e ) interface is n
12770 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 54 ot threadsafe. T
12780 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a he application.*
12790 2a 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 * must ensure th
127a0 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 at no other SQLi
127b0 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 te interfaces ar
127c0 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 e invoked by oth
127d0 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 er.** threads wh
127e0 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 ile sqlite3_conf
127f0 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e ig() is running.
12800 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 </b>.**.** The s
12810 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
12820 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 6d 61 79 interface.** may
12830 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 only be invoked
12840 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 prior to librar
12850 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e y initialization
12860 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 using.** [sqlit
12870 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d e3_initialize()]
12880 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f or after shutdo
12890 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 wn by [sqlite3_s
128a0 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e hutdown()]..** ^
128b0 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 If sqlite3_confi
128c0 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 g() is called af
128d0 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 ter [sqlite3_ini
128e0 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 tialize()] and b
128f0 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 efore.** [sqlite
12900 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 3_shutdown()] th
12910 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 en it will retur
12920 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e n SQLITE_MISUSE.
12930 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 .** Note, howeve
12940 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 r, that ^sqlite3
12950 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 _config() can be
12960 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 called as part
12970 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d of the.** implem
12980 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 entation of an a
12990 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
129a0 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 ed [sqlite3_os_i
129b0 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 nit()]..**.** Th
129c0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
129d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 to sqlite3_conf
129e0 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 ig() is an integ
129f0 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 er.** [configura
12a00 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 tion option] tha
12a10 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 t determines.**
12a20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 what property of
12a30 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 SQLite is to be
12a40 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 configured. Su
12a50 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e bsequent argumen
12a60 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e ts.** vary depen
12a70 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e ding on the [con
12a80 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
12a90 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 n].** in the fir
12aa0 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a st argument..**.
12ab0 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 ** ^When a confi
12ac0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 guration option
12ad0 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f is set, sqlite3_
12ae0 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 config() returns
12af0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a [SQLITE_OK]..**
12b00 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 ^If the option
12b10 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 is unknown or SQ
12b20 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 Lite is unable t
12b30 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e o set the option
12b40 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f .** then this ro
12b50 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 utine returns a
12b60 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 non-zero [error
12b70 63 6f 64 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 code]..*/.SQLITE
12b80 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f _API int SQLITE_
12b90 43 44 45 43 4c 20 73 71 6c 69 74 65 33 5f 63 6f CDECL sqlite3_co
12ba0 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a nfig(int, ...);.
12bb0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
12bc0 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 Configure datab
12bd0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a ase connections.
12be0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
12bf0 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c e3.**.** The sql
12c00 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
12c10 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 interface is us
12c20 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 ed to make confi
12c30 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e guration.** chan
12c40 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 ges to a [databa
12c50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 se connection].
12c60 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 The interface i
12c70 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 s similar to.**
12c80 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
12c90 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74 )] except that t
12ca0 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 he changes apply
12cb0 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 to a single.**
12cc0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
12cd0 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 tion] (specified
12ce0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 in the first ar
12cf0 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 gument)..**.** T
12d00 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
12d10 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 nt to sqlite3_db
12d20 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 _config(D,V,...)
12d30 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c is the.** [SQL
12d40 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f ITE_DBCONFIG_LOO
12d50 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 KASIDE | configu
12d60 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 ration verb] - a
12d70 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a n integer code .
12d80 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 ** that indicate
12d90 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 s what aspect of
12da0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
12db0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 onnection] is be
12dc0 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a ing configured..
12dd0 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 ** Subsequent ar
12de0 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 guments vary dep
12df0 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f ending on the co
12e00 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 nfiguration verb
12e10 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 ..**.** ^Calls t
12e20 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e o sqlite3_db_con
12e30 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c fig() return SQL
12e40 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e ITE_OK if and on
12e50 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c ly if.** the cal
12e60 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 l is considered
12e70 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53 successful..*/.S
12e80 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 QLITE_API int SQ
12e90 4c 49 54 45 5f 43 44 45 43 4c 20 73 71 6c 69 74 LITE_CDECL sqlit
12ea0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c e3_db_config(sql
12eb0 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e ite3*, int op, .
12ec0 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ..);../*.** CAPI
12ed0 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 3REF: Memory All
12ee0 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 ocation Routines
12ef0 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e .**.** An instan
12f00 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 ce of this objec
12f10 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e t defines the in
12f20 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 terface between
12f30 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f SQLite.** and lo
12f40 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 w-level memory a
12f50 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e llocation routin
12f60 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f es..**.** This o
12f70 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e bject is used in
12f80 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 only one place
12f90 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e in the SQLite in
12fa0 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f terface..** A po
12fb0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 inter to an inst
12fc0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a ance of this obj
12fd0 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d ect is the argum
12fe0 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 ent to.** [sqlit
12ff0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 e3_config()] whe
13000 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 n the configurat
13010 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a ion option is.**
13020 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
13030 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 MALLOC] or [SQLI
13040 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c TE_CONFIG_GETMAL
13050 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 LOC]. .** By cr
13060 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e eating an instan
13070 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 ce of this objec
13080 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 t.** and passing
13090 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f it to [sqlite3_
130a0 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f config]([SQLITE_
130b0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a CONFIG_MALLOC]).
130c0 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 ** during config
130d0 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c uration, an appl
130e0 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 ication can spec
130f0 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 ify an alternati
13100 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c ve.** memory all
13110 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 ocation subsyste
13120 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 m for SQLite to
13130 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 use for all of i
13140 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 ts.** dynamic me
13150 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a mory needs..**.*
13160 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 * Note that SQLi
13170 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 te comes with se
13180 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 veral [built-in
13190 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
131a0 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 s].** that are p
131b0 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 erfectly adequat
131c0 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 e for the overwh
131d0 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 elming majority
131e0 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a of applications.
131f0 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 ** and that this
13200 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 object is only
13210 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 useful to a tiny
13220 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 minority of app
13230 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 lications.** wit
13240 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 h specialized me
13250 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
13260 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 requirements. T
13270 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a his object is.**
13280 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e also used durin
13290 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c g testing of SQL
132a0 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 ite in order to
132b0 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 specify an alter
132c0 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 native.** memory
132d0 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 allocator that
132e0 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 simulates memory
132f0 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 out-of-memory c
13300 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 onditions in.**
13310 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 order to verify
13320 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f that SQLite reco
13330 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 vers gracefully
13340 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e from such.** con
13350 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 ditions..**.** T
13360 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 he xMalloc, xRea
13370 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 lloc, and xFree
13380 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 methods must wor
13390 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 k like the.** ma
133a0 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 lloc(), realloc(
133b0 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e ) and free() fun
133c0 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 ctions from the
133d0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 standard C libra
133e0 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 ry..** ^SQLite g
133f0 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 uarantees that t
13400 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
13410 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f nt to.** xReallo
13420 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 c is always a va
13430 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 lue returned by
13440 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 a prior call to
13450 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 xRoundup..**.**
13460 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 xSize should ret
13470 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 urn the allocate
13480 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f d size of a memo
13490 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a ry allocation.**
134a0 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 previously obta
134b0 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f ined from xMallo
134c0 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 c or xRealloc.
134d0 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 The allocated si
134e0 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 ze.** is always
134f0 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 at least as big
13500 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 as the requested
13510 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 size but may be
13520 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 larger..**.** T
13530 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 he xRoundup meth
13540 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 od returns what
13550 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c would be the all
13560 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a ocated size of.*
13570 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 * a memory alloc
13580 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 ation given a pa
13590 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 rticular request
135a0 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d ed size. Most m
135b0 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 emory.** allocat
135c0 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d ors round up mem
135d0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 ory allocations
135e0 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 at least to the
135f0 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a next multiple.**
13600 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c of 8. Some all
13610 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 ocators round up
13620 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c to a larger mul
13630 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f tiple or to a po
13640 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 wer of 2..** Eve
13650 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ry memory alloca
13660 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d tion request com
13670 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b ing in through [
13680 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
13690 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 ].** or [sqlite3
136a0 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 _realloc()] firs
136b0 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 t calls xRoundup
136c0 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 . If xRoundup r
136d0 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 eturns 0, .** th
136e0 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f at causes the co
136f0 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f rresponding memo
13700 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f ry allocation to
13710 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 fail..**.** The
13720 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e xInit method in
13730 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 itializes the me
13740 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 mory allocator.
13750 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a For example,.**
13760 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 it might alloca
13770 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d te any require m
13780 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 utexes or initia
13790 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 lize internal da
137a0 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 ta.** structures
137b0 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e . The xShutdown
137c0 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b method is invok
137d0 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 ed (indirectly)
137e0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 by.** [sqlite3_s
137f0 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 hutdown()] and s
13800 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 hould deallocate
13810 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 any resources a
13820 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 cquired.** by xI
13830 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 nit. The pAppDa
13840 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 ta pointer is us
13850 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 ed as the only p
13860 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 arameter to.** x
13870 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f Init and xShutdo
13880 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 wn..**.** SQLite
13890 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 holds the [SQLI
138a0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f TE_MUTEX_STATIC_
138b0 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 MASTER] mutex wh
138c0 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a en it invokes.**
138d0 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f the xInit metho
138e0 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 d, so the xInit
138f0 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 method need not
13900 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 be threadsafe.
13910 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e The.** xShutdown
13920 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 method is only
13930 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c called from [sql
13940 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d ite3_shutdown()]
13950 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e so it does.** n
13960 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 ot need to be th
13970 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e readsafe either.
13980 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 For all other
13990 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a methods, SQLite.
139a0 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 ** holds the [SQ
139b0 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 LITE_MUTEX_STATI
139c0 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 C_MEM] mutex as
139d0 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b long as the.** [
139e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 SQLITE_CONFIG_ME
139f0 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 MSTATUS] configu
13a00 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 ration option is
13a10 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 turned on (whic
13a20 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 h.** it is by de
13a30 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 fault) and so th
13a40 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 e methods are au
13a50 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 tomatically seri
13a60 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 alized..** Howev
13a70 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 er, if [SQLITE_C
13a80 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d ONFIG_MEMSTATUS]
13a90 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 is disabled, th
13aa0 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 en the other.**
13ab0 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 methods must be
13ac0 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c threadsafe or el
13ad0 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 se make their ow
13ae0 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 n arrangements f
13af0 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 or.** serializat
13b00 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 ion..**.** SQLit
13b10 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 e will never inv
13b20 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 oke xInit() more
13b30 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f than once witho
13b40 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e ut an intervenin
13b50 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 g.** call to xSh
13b60 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 utdown()..*/.typ
13b70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
13b80 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 te3_mem_methods
13b90 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
13ba0 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 ods;.struct sqli
13bb0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 te3_mem_methods
13bc0 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c {. void *(*xMal
13bd0 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 loc)(int);
13be0 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c /* Memory all
13bf0 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e ocation function
13c00 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 */. void (*xFr
13c10 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 ee)(void*);
13c20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 /* Free a p
13c30 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 rior allocation
13c40 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 */. void *(*xRe
13c50 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 alloc)(void*,int
13c60 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e ); /* Resize an
13c70 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 allocation */.
13c80 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f int (*xSize)(vo
13c90 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 id*);
13ca0 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 /* Return the si
13cb0 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 ze of an allocat
13cc0 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 ion */. int (*x
13cd0 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 Roundup)(int);
13ce0 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 /* Round
13cf0 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 up request size
13d00 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 to allocation s
13d10 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 ize */. int (*x
13d20 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 Init)(void*);
13d30 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 /* Initi
13d40 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 alize the memory
13d50 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 allocator */.
13d60 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e void (*xShutdown
13d70 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f )(void*); /
13d80 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 * Deinitialize t
13d90 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
13da0 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 tor */. void *p
13db0 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 AppData;
13dc0 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d /* Argum
13dd0 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 ent to xInit() a
13de0 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a nd xShutdown() *
13df0 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.};../*.** CAPI
13e00 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 3REF: Configurat
13e10 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b ion Options.** K
13e20 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 EYWORDS: {config
13e30 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a uration option}.
13e40 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 **.** These cons
13e50 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 tants are the av
13e60 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 ailable integer
13e70 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
13e80 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 tions that.** ca
13e90 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 n be passed as t
13ea0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
13eb0 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 t to the [sqlite
13ec0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 3_config()] inte
13ed0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 rface..**.** New
13ee0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
13ef0 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 ptions may be ad
13f00 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 ded in future re
13f10 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 leases of SQLite
13f20 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f ..** Existing co
13f30 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
13f40 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 ons might be dis
13f50 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c continued. Appl
13f60 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 ications.** shou
13f70 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 ld check the ret
13f80 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 urn code from [s
13f90 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
13fa0 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 to make sure th
13fb0 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 at.** the call w
13fc0 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c orked. The [sql
13fd0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 ite3_config()] i
13fe0 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 nterface will re
13ff0 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 turn a.** non-ze
14000 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 ro [error code]
14010 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 if a discontinue
14020 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 d or unsupported
14030 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
14040 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f ption.** is invo
14050 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a ked..**.** <dl>.
14060 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
14070 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d IG_SINGLETHREAD]
14080 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
14090 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 FIG_SINGLETHREAD
140a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
140b0 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 re are no argume
140c0 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 nts to this opti
140d0 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f on. ^This optio
140e0 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 n sets the.** [t
140f0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 hreading mode] t
14100 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e o Single-thread.
14110 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 In other words
14120 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a , it disables.**
14130 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e all mutexing an
14140 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e d puts SQLite in
14150 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 to a mode where
14160 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 it can only be u
14170 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 sed.** by a sing
14180 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 le thread. ^If
14190 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
141a0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 led with.** the
141b0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 [SQLITE_THREADSA
141c0 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 FE | SQLITE_THRE
141d0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c ADSAFE=0] compil
141e0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 e-time option th
141f0 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 en.** it is not
14200 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e possible to chan
14210 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e ge the [threadin
14220 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 g mode] from its
14230 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 default.** valu
14240 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 e of Single-thre
14250 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 ad and so [sqlit
14260 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c e3_config()] wil
14270 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 l return .** [SQ
14280 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 LITE_ERROR] if c
14290 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 alled with the S
142a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e QLITE_CONFIG_SIN
142b0 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e GLETHREAD.** con
142c0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
142d0 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b n.</dd>.**.** [[
142e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
142f0 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e LTITHREAD]] <dt>
14300 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
14310 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a LTITHREAD</dt>.*
14320 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 * <dd>There are
14330 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 no arguments to
14340 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 this option. ^T
14350 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 his option sets
14360 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e the.** [threadin
14370 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 g mode] to Multi
14380 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 -thread. In oth
14390 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 er words, it dis
143a0 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e ables.** mutexin
143b0 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 g on [database c
143c0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b onnection] and [
143d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
143e0 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 nt] objects..**
143f0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 The application
14400 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 is responsible f
14410 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 or serializing a
14420 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 ccess to.** [dat
14430 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
14440 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 s] and [prepared
14450 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 statements]. B
14460 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 ut other mutexes
14470 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 .** are enabled
14480 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 so that SQLite w
14490 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 ill be safe to u
144a0 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 se in a multi-th
144b0 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f readed.** enviro
144c0 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 nment as long as
144d0 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 no two threads
144e0 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 attempt to use t
144f0 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 he same.** [data
14500 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
14510 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d at the same tim
14520 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 e. ^If SQLite i
14530 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a s compiled with.
14540 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 ** the [SQLITE_T
14550 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 HREADSAFE | SQLI
14560 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d TE_THREADSAFE=0]
14570 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
14580 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 tion then.** it
14590 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 is not possible
145a0 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 to set the Multi
145b0 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 -thread [threadi
145c0 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 ng mode] and.**
145d0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
145e0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b )] will return [
145f0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 SQLITE_ERROR] if
14600 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 called with the
14610 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 .** SQLITE_CONFI
14620 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f G_MULTITHREAD co
14630 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
14640 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b on.</dd>.**.** [
14650 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 [SQLITE_CONFIG_S
14660 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e ERIALIZED]] <dt>
14670 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 SQLITE_CONFIG_SE
14680 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a RIALIZED</dt>.**
14690 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e <dd>There are n
146a0 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 o arguments to t
146b0 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 his option. ^Th
146c0 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 is option sets t
146d0 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 he.** [threading
146e0 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c mode] to Serial
146f0 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 ized. In other w
14700 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f ords, this optio
14710 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c n enables.** all
14720 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 mutexes includi
14730 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65 ng the recursive
14740 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b .** mutexes on [
14750 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
14760 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 ion] and [prepar
14770 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 ed statement] ob
14780 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 jects..** In thi
14790 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 s mode (which is
147a0 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 the default whe
147b0 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 n SQLite is comp
147c0 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 iled with.** [SQ
147d0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
147e0 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 1]) the SQLite l
147f0 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 ibrary will itse
14800 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 lf serialize acc
14810 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 ess.** to [datab
14820 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d ase connections]
14830 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 and [prepared s
14840 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 tatements] so th
14850 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 at the.** applic
14860 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f ation is free to
14870 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 use the same [d
14880 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
14890 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 on] or the.** sa
148a0 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 me [prepared sta
148b0 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 tement] in diffe
148c0 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 rent threads at
148d0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a the same time..*
148e0 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 * ^If SQLite is
148f0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a compiled with.**
14900 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
14910 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 EADSAFE | SQLITE
14920 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 _THREADSAFE=0] c
14930 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
14940 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 on then.** it is
14950 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f not possible to
14960 20 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 set the Seriali
14970 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d zed [threading m
14980 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ode] and.** [sql
14990 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 ite3_config()] w
149a0 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 ill return [SQLI
149b0 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c TE_ERROR] if cal
149c0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 led with the.**
149d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 SQLITE_CONFIG_SE
149e0 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 RIALIZED configu
149f0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f ration option.</
14a00 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
14a10 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 TE_CONFIG_MALLOC
14a20 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
14a30 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e NFIG_MALLOC</dt>
14a40 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 .** <dd> ^(The S
14a50 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c QLITE_CONFIG_MAL
14a60 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 LOC option takes
14a70 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 a single argume
14a80 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 nt which is .**
14a90 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
14aa0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 instance of the
14ab0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 [sqlite3_mem_met
14ac0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e hods] structure.
14ad0 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 .** The argument
14ae0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c specifies.** al
14af0 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 ternative low-le
14b00 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 vel memory alloc
14b10 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 ation routines t
14b20 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 o be used in pla
14b30 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d ce of.** the mem
14b40 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 ory allocation r
14b50 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e outines built in
14b60 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 to SQLite.)^ ^SQ
14b70 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 Lite makes.** it
14b80 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f s own private co
14b90 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e py of the conten
14ba0 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 t of the [sqlite
14bb0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 3_mem_methods] s
14bc0 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f tructure.** befo
14bd0 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f re the [sqlite3_
14be0 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 config()] call r
14bf0 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a eturns.</dd>.**.
14c00 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
14c10 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c IG_GETMALLOC]] <
14c20 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
14c30 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a _GETMALLOC</dt>.
14c40 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 ** <dd> ^(The SQ
14c50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
14c60 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b ALLOC option tak
14c70 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 es a single argu
14c80 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 ment which.** is
14c90 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
14ca0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 instance of the
14cb0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 [sqlite3_mem_me
14cc0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 thods] structure
14cd0 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 ..** The [sqlite
14ce0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 3_mem_methods].*
14cf0 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 * structure is f
14d00 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 illed with the c
14d10 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 urrently defined
14d20 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
14d30 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a on routines.)^.*
14d40 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 * This option ca
14d50 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 n be used to ove
14d60 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c rload the defaul
14d70 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 t memory allocat
14d80 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 ion.** routines
14d90 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 with a wrapper t
14da0 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 hat simulations
14db0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
14dc0 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 n failure or.**
14dd0 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 tracks memory us
14de0 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 age, for example
14df0 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b . </dd>.**.** [[
14e00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 SQLITE_CONFIG_ME
14e10 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 MSTATUS]] <dt>SQ
14e20 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 LITE_CONFIG_MEMS
14e30 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 TATUS</dt>.** <d
14e40 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 d> ^The SQLITE_C
14e50 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 ONFIG_MEMSTATUS
14e60 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e option takes sin
14e70 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 gle argument of
14e80 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 type int,.** int
14e90 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f erpreted as a bo
14ea0 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 olean, which ena
14eb0 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 bles or disables
14ec0 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 the collection
14ed0 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c of.** memory all
14ee0 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 ocation statisti
14ef0 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 cs. ^(When memor
14f00 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 y allocation sta
14f10 74 69 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 tistics are.** d
14f20 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c isabled, the fol
14f30 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e lowing SQLite in
14f40 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 terfaces become
14f50 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a non-operational:
14f60 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 .** <ul>.**
14f70 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 <li> [sqlite3_me
14f80 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 mory_used()].**
14f90 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f <li> [sqlite3_
14fa0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 memory_highwater
14fb0 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 ()].** <li> [s
14fc0 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 qlite3_soft_heap
14fd0 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 _limit64()].**
14fe0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 <li> [sqlite3_s
14ff0 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20 tatus64()].**
15000 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f </ul>)^.** ^Memo
15010 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 ry allocation st
15020 61 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 atistics are ena
15030 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 bled by default
15040 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 unless SQLite is
15050 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 .** compiled wit
15060 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c h [SQLITE_DEFAUL
15070 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 T_MEMSTATUS]=0 i
15080 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d n which case mem
15090 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f ory.** allocatio
150a0 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 n statistics are
150b0 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 disabled by def
150c0 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a ault..** </dd>.*
150d0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
150e0 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c NFIG_SCRATCH]] <
150f0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
15100 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a _SCRATCH</dt>.**
15110 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 <dd> ^The SQLIT
15120 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 E_CONFIG_SCRATCH
15130 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 option specifie
15140 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 s a static memor
15150 79 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 y buffer.** that
15160 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 SQLite can use
15170 66 6f 72 20 73 63 72 61 74 63 68 20 6d 65 6d 6f for scratch memo
15180 72 79 2e 20 20 5e 28 54 68 65 72 65 20 61 72 65 ry. ^(There are
15190 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 three arguments
151a0 0a 2a 2a 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f .** to SQLITE_CO
151b0 4e 46 49 47 5f 53 43 52 41 54 43 48 3a 20 20 41 NFIG_SCRATCH: A
151c0 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 pointer an 8-by
151d0 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 te.** aligned me
151e0 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d mory buffer from
151f0 20 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74 which the scrat
15200 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 ch allocations w
15210 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c ill be.** drawn,
15220 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 the size of eac
15230 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 h scratch alloca
15240 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e tion (sz),.** an
15250 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 d the maximum nu
15260 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 mber of scratch
15270 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e allocations (N).
15280 29 5e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 )^.** The first
15290 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 argument must be
152a0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
152b0 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 8-byte aligned
152c0 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 buffer.** of at
152d0 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 least sz*N bytes
152e0 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e of memory..** ^
152f0 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 6f 74 20 SQLite will not
15300 75 73 65 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e use more than on
15310 65 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 e scratch buffer
15320 73 20 70 65 72 20 74 68 72 65 61 64 2e 0a 2a 2a s per thread..**
15330 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 ^SQLite will ne
15340 76 65 72 20 72 65 71 75 65 73 74 20 61 20 73 63 ver request a sc
15350 72 61 74 63 68 20 62 75 66 66 65 72 20 74 68 61 ratch buffer tha
15360 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 t is more than 6
15370 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 .** times the da
15380 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 tabase page size
15390 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 ..** ^If SQLite
153a0 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 needs needs addi
153b0 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 tional.** scratc
153c0 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 h memory beyond
153d0 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 what is provided
153e0 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 by this configu
153f0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 ration option, t
15400 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 hen .** [sqlite3
15410 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 _malloc()] will
15420 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 be used to obtai
15430 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 n the memory nee
15440 64 65 64 2e 3c 70 3e 0a 2a 2a 20 5e 57 68 65 6e ded.<p>.** ^When
15450 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
15460 20 70 72 6f 76 69 64 65 73 20 61 6e 79 20 61 6d provides any am
15470 6f 75 6e 74 20 6f 66 20 73 63 72 61 74 63 68 20 ount of scratch
15480 6d 65 6d 6f 72 79 20 75 73 69 6e 67 0a 2a 2a 20 memory using.**
15490 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 SQLITE_CONFIG_SC
154a0 52 41 54 43 48 2c 20 53 51 4c 69 74 65 20 61 76 RATCH, SQLite av
154b0 6f 69 64 73 20 75 6e 6e 65 63 65 73 73 61 72 79 oids unnecessary
154c0 20 6c 61 72 67 65 0a 2a 2a 20 5b 73 71 6c 69 74 large.** [sqlit
154d0 65 33 5f 6d 61 6c 6c 6f 63 7c 68 65 61 70 20 61 e3_malloc|heap a
154e0 6c 6c 6f 63 61 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 llocations]..**
154f0 54 68 69 73 20 63 61 6e 20 68 65 6c 70 20 5b 52 This can help [R
15500 6f 62 73 6f 6e 20 70 72 6f 6f 66 7c 70 72 65 76 obson proof|prev
15510 65 6e 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ent memory alloc
15520 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 73 5d 20 ation failures]
15530 64 75 65 20 74 6f 20 68 65 61 70 0a 2a 2a 20 66 due to heap.** f
15540 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 20 ragmentation in
15550 6c 6f 77 2d 6d 65 6d 6f 72 79 20 65 6d 62 65 64 low-memory embed
15560 64 65 64 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 20 ded systems..**
15570 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
15580 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 LITE_CONFIG_PAGE
15590 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 CACHE]] <dt>SQLI
155a0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 TE_CONFIG_PAGECA
155b0 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e CHE</dt>.** <dd>
155c0 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e ^The SQLITE_CON
155d0 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 6f 70 FIG_PAGECACHE op
155e0 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 tion specifies a
155f0 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 memory pool.**
15600 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 that SQLite can
15610 75 73 65 20 66 6f 72 20 74 68 65 20 64 61 74 61 use for the data
15620 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 base page cache
15630 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 with the default
15640 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 page.** cache i
15650 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 mplementation.
15660 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 .** This configu
15670 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 ration option is
15680 20 61 20 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61 a no-op if an a
15690 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
156a0 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 e page.** cache
156b0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 implementation i
156c0 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 s loaded using t
156d0 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 he [SQLITE_CONFI
156e0 47 5f 50 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e G_PCACHE2]..** ^
156f0 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 There are three
15700 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c arguments to SQL
15710 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 ITE_CONFIG_PAGEC
15720 41 43 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 ACHE: A pointer
15730 74 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 to.** 8-byte ali
15740 67 6e 65 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65 gned memory (pMe
15750 6d 29 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 m), the size of
15760 65 61 63 68 20 70 61 67 65 20 63 61 63 68 65 20 each page cache
15770 6c 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e line (sz),.** an
15780 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 d the number of
15790 63 61 63 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e cache lines (N).
157a0 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d .** The sz argum
157b0 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 ent should be th
157c0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 e size of the la
157d0 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 rgest database p
157e0 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 age.** (a power
157f0 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 of two between 5
15800 31 32 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c 12 and 65536) pl
15810 75 73 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79 us some extra by
15820 74 65 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 tes for each.**
15830 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 page header. ^T
15840 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 he number of ext
15850 72 61 20 62 79 74 65 73 20 6e 65 65 64 65 64 20 ra bytes needed
15860 62 79 20 74 68 65 20 70 61 67 65 20 68 65 61 64 by the page head
15870 65 72 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 er.** can be det
15880 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 5b 53 ermined using [S
15890 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 QLITE_CONFIG_PCA
158a0 43 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e CHE_HDRSZ]..** ^
158b0 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 It is harmless,
158c0 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 apart from the w
158d0 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a asted memory,.**
158e0 20 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61 for the sz para
158f0 6d 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67 meter to be larg
15900 65 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72 er than necessar
15910 79 2e 20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 y. The pMem.**
15920 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 argument must be
15930 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 either a NULL p
15940 6f 69 6e 74 65 72 20 6f 72 20 61 20 70 6f 69 6e ointer or a poin
15950 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 ter to an 8-byte
15960 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 .** aligned bloc
15970 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61 k of memory of a
15980 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 t least sz*N byt
15990 65 73 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a es, otherwise.**
159a0 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 subsequent beha
159b0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 vior is undefine
159c0 64 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d d..** ^When pMem
159d0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 is not NULL, SQ
159e0 4c 69 74 65 20 77 69 6c 6c 20 73 74 72 69 76 65 Lite will strive
159f0 20 74 6f 20 75 73 65 20 74 68 65 20 6d 65 6d 6f to use the memo
15a00 72 79 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74 ry provided.** t
15a10 6f 20 73 61 74 69 73 66 79 20 70 61 67 65 20 63 o satisfy page c
15a20 61 63 68 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c ache needs, fall
15a30 69 6e 67 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c ing back to [sql
15a40 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 ite3_malloc()] i
15a50 66 0a 2a 2a 20 61 20 70 61 67 65 20 63 61 63 68 f.** a page cach
15a60 65 20 6c 69 6e 65 20 69 73 20 6c 61 72 67 65 72 e line is larger
15a70 20 74 68 61 6e 20 73 7a 20 62 79 74 65 73 20 6f than sz bytes o
15a80 72 20 69 66 20 61 6c 6c 20 6f 66 20 74 68 65 20 r if all of the
15a90 70 4d 65 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69 pMem buffer.** i
15aa0 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 s exhausted..**
15ab0 5e 49 66 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c ^If pMem is NULL
15ac0 20 61 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 and N is non-ze
15ad0 72 6f 2c 20 74 68 65 6e 20 65 61 63 68 20 64 61 ro, then each da
15ae0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
15af0 6e 0a 2a 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69 n.** does an ini
15b00 74 69 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 tial bulk alloca
15b10 74 69 6f 6e 20 66 6f 72 20 70 61 67 65 20 63 61 tion for page ca
15b20 63 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 che memory.** fr
15b30 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c om [sqlite3_mall
15b40 6f 63 28 29 5d 20 73 75 66 66 69 63 69 65 6e 74 oc()] sufficient
15b50 20 66 6f 72 20 4e 20 63 61 63 68 65 20 6c 69 6e for N cache lin
15b60 65 73 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 es if N is posit
15b70 69 76 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 ive or.** of -10
15b80 32 34 2a 4e 20 62 79 74 65 73 20 69 66 20 4e 20 24*N bytes if N
15b90 69 73 20 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e is negative, . ^
15ba0 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a If additional.**
15bb0 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f page cache memo
15bc0 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 ry is needed bey
15bd0 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 ond what is prov
15be0 69 64 65 64 20 62 79 20 74 68 65 20 69 6e 69 74 ided by the init
15bf0 69 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f ial.** allocatio
15c00 6e 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 67 n, then SQLite g
15c10 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f oes to [sqlite3_
15c20 6d 61 6c 6c 6f 63 28 29 5d 20 73 65 70 61 72 61 malloc()] separa
15c30 74 65 6c 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a tely for each.**
15c40 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 61 63 68 additional cach
15c50 65 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a e line. </dd>.**
15c60 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
15c70 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 FIG_HEAP]] <dt>S
15c80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 QLITE_CONFIG_HEA
15c90 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e P</dt>.** <dd> ^
15ca0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 The SQLITE_CONFI
15cb0 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 G_HEAP option sp
15cc0 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 ecifies a static
15cd0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a memory buffer .
15ce0 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 ** that SQLite w
15cf0 69 6c 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 ill use for all
15d00 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d of its dynamic m
15d10 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
15d20 20 6e 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 needs.** beyond
15d30 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20 those provided
15d40 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 for by [SQLITE_C
15d50 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 ONFIG_SCRATCH] a
15d60 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f nd.** [SQLITE_CO
15d70 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e NFIG_PAGECACHE].
15d80 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f .** ^The SQLITE_
15d90 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 CONFIG_HEAP opti
15da0 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c on is only avail
15db0 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 able if SQLite i
15dc0 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 s compiled.** wi
15dd0 74 68 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 th either [SQLIT
15de0 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 E_ENABLE_MEMSYS3
15df0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 ] or [SQLITE_ENA
15e00 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 BLE_MEMSYS5] and
15e10 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c returns.** [SQL
15e20 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e ITE_ERROR] if in
15e30 76 6f 6b 65 64 20 6f 74 68 65 72 77 69 73 65 2e voked otherwise.
15e40 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 .** ^There are t
15e50 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 hree arguments t
15e60 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f o SQLITE_CONFIG_
15e70 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 HEAP:.** An 8-by
15e80 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 te aligned point
15e90 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 er to the memory
15ea0 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 ,.** the number
15eb0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 of bytes in the
15ec0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 memory buffer, a
15ed0 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 nd the minimum a
15ee0 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a llocation size..
15ef0 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 ** ^If the first
15f00 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 pointer (the me
15f10 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 mory pointer) is
15f20 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 NULL, then SQLi
15f30 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f te reverts.** to
15f40 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 using its defau
15f50 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 lt memory alloca
15f60 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 tor (the system
15f70 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 malloc() impleme
15f80 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 ntation),.** und
15f90 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 oing any prior i
15fa0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 nvocation of [SQ
15fb0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c LITE_CONFIG_MALL
15fc0 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a OC]. ^If the.**
15fd0 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 memory pointer
15fe0 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e is not NULL then
15ff0 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 the alternative
16000 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 memory.** alloc
16010 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 ator is engaged
16020 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 to handle all of
16030 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 SQLites memory
16040 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 allocation needs
16050 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 ..** The first p
16060 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f ointer (the memo
16070 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 ry pointer) must
16080 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 be aligned to a
16090 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e n 8-byte.** boun
160a0 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 dary or subseque
160b0 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 nt behavior of S
160c0 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e QLite will be un
160d0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 defined..** The
160e0 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 minimum allocati
160f0 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 on size is cappe
16100 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 d at 2**12. Reas
16110 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a onable values.**
16120 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d for the minimum
16130 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 allocation size
16140 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 are 2**5 throug
16150 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a h 2**8.</dd>.**.
16160 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
16170 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 IG_MUTEX]] <dt>S
16180 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 QLITE_CONFIG_MUT
16190 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 EX</dt>.** <dd>
161a0 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e ^(The SQLITE_CON
161b0 46 49 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e FIG_MUTEX option
161c0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 takes a single
161d0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 argument which i
161e0 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 s a.** pointer t
161f0 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 o an instance of
16200 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 the [sqlite3_mu
16210 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 tex_methods] str
16220 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 ucture..** The a
16230 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 rgument specifie
16240 73 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f s alternative lo
16250 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f w-level mutex ro
16260 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 utines to be use
16270 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 d.** in place th
16280 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 e mutex routines
16290 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 built into SQLi
162a0 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d te.)^ ^SQLite m
162b0 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a akes a copy of.*
162c0 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 * the content of
162d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 the [sqlite3_mu
162e0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 tex_methods] str
162f0 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 ucture before th
16300 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 e call to.** [sq
16310 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
16320 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c returns. ^If SQL
16330 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
16340 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c with.** the [SQL
16350 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c ITE_THREADSAFE |
16360 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 SQLITE_THREADSA
16370 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 FE=0] compile-ti
16380 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a me option then.*
16390 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 * the entire mut
163a0 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 exing subsystem
163b0 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 is omitted from
163c0 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 the build and he
163d0 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 nce calls to.**
163e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
163f0 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 )] with the SQLI
16400 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 TE_CONFIG_MUTEX
16410 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
16420 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 tion will.** ret
16430 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f urn [SQLITE_ERRO
16440 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b R].</dd>.**.** [
16450 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 [SQLITE_CONFIG_G
16460 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 ETMUTEX]] <dt>SQ
16470 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
16480 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 UTEX</dt>.** <dd
16490 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 > ^(The SQLITE_C
164a0 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 6f ONFIG_GETMUTEX o
164b0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 ption takes a si
164c0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 ngle argument wh
164d0 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e ich.** is a poin
164e0 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e ter to an instan
164f0 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 ce of the [sqlit
16500 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 e3_mutex_methods
16510 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 ] structure. Th
16520 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 e.** [sqlite3_mu
16530 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 tex_methods].**
16540 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c structure is fil
16550 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 led with the cur
16560 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d rently defined m
16570 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e utex routines.)^
16580 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 .** This option
16590 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f can be used to o
165a0 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 verload the defa
165b0 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 ult mutex alloca
165c0 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 tion.** routines
165d0 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 with a wrapper
165e0 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 used to track mu
165f0 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 tex usage for pe
16600 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f rformance.** pro
16610 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e filing or testin
16620 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 g, for example.
16630 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 ^If SQLite is
16640 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a compiled with.**
16650 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
16660 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 EADSAFE | SQLITE
16670 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 _THREADSAFE=0] c
16680 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
16690 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 on then.** the e
166a0 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 ntire mutexing s
166b0 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 ubsystem is omit
166c0 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 ted from the bui
166d0 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c ld and hence cal
166e0 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 ls to.** [sqlite
166f0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 3_config()] with
16700 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 the SQLITE_CONF
16710 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 IG_GETMUTEX conf
16720 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
16730 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 will.** return
16740 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c [SQLITE_ERROR].<
16750 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
16760 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 ITE_CONFIG_LOOKA
16770 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 SIDE]] <dt>SQLIT
16780 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 E_CONFIG_LOOKASI
16790 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 DE</dt>.** <dd>
167a0 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e ^(The SQLITE_CON
167b0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 FIG_LOOKASIDE op
167c0 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 tion takes two a
167d0 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 rguments that de
167e0 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 termine.** the d
167f0 65 66 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c efault size of l
16800 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 ookaside memory
16810 6f 6e 20 65 61 63 68 20 5b 64 61 74 61 62 61 73 on each [databas
16820 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a e connection]..*
16830 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 * The first argu
16840 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 ment is the.** s
16850 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b ize of each look
16860 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f aside buffer slo
16870 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 t and the second
16880 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f is the number o
16890 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 f.** slots alloc
168a0 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 ated to each dat
168b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
168c0 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f .)^ ^(SQLITE_CO
168d0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a NFIG_LOOKASIDE.*
168e0 2a 20 73 65 74 73 20 74 68 65 20 3c 69 3e 64 65 * sets the <i>de
168f0 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 fault</i> lookas
16900 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 ide size. The [S
16910 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c QLITE_DBCONFIG_L
16920 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 OOKASIDE].** opt
16930 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ion to [sqlite3_
16940 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e db_config()] can
16950 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e be used to chan
16960 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 ge the lookaside
16970 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f .** configuratio
16980 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 n on individual
16990 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c connections.)^ <
169a0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
169b0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 ITE_CONFIG_PCACH
169c0 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f E2]] <dt>SQLITE_
169d0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f CONFIG_PCACHE2</
169e0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 dt>.** <dd> ^(Th
169f0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
16a00 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 PCACHE2 option t
16a10 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 akes a single ar
16a20 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 gument which is
16a30 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f .** a pointer to
16a40 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 an [sqlite3_pca
16a50 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 che_methods2] ob
16a60 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 ject. This obje
16a70 63 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 ct specifies.**
16a80 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f the interface to
16a90 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 a custom page c
16aa0 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 ache implementat
16ab0 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 ion.)^.** ^SQLit
16ac0 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f e makes a copy o
16ad0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 f the [sqlite3_p
16ae0 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 cache_methods2]
16af0 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a object.</dd>.**.
16b00 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
16b10 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 IG_GETPCACHE2]]
16b20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
16b30 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 G_GETPCACHE2</dt
16b40 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 >.** <dd> ^(The
16b50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
16b60 54 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 TPCACHE2 option
16b70 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 takes a single a
16b80 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a rgument which.**
16b90 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
16ba0 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 an [sqlite3_pca
16bb0 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 che_methods2] ob
16bc0 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f ject. SQLite co
16bd0 70 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 pies of.** the c
16be0 75 72 72 65 6e 74 20 70 61 67 65 20 63 61 63 68 urrent page cach
16bf0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
16c00 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 into that objec
16c10 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a t.)^ </dd>.**.**
16c20 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
16c30 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 _LOG]] <dt>SQLIT
16c40 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 E_CONFIG_LOG</dt
16c50 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 >.** <dd> The SQ
16c60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 LITE_CONFIG_LOG
16c70 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 option is used t
16c80 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20 o configure the
16c90 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c SQLite.** global
16ca0 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a [error log]..**
16cb0 20 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f (^The SQLITE_CO
16cc0 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 NFIG_LOG option
16cd0 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 takes two argume
16ce0 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 nts: a pointer t
16cf0 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 o a.** function
16d00 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e with a call sign
16d10 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 ature of void(*)
16d20 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 (void*,int,const
16d30 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 char*), .** and
16d40 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f a pointer to vo
16d50 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 id. ^If the func
16d60 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 tion pointer is
16d70 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a not NULL, it is.
16d80 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 ** invoked by [s
16d90 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f qlite3_log()] to
16da0 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f process each lo
16db0 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 gging event. ^I
16dc0 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f f the.** functio
16dd0 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c n pointer is NUL
16de0 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f L, the [sqlite3_
16df0 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 log()] interface
16e00 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 becomes a no-op
16e10 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 ..** ^The void p
16e20 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 ointer that is t
16e30 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
16e40 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e nt to SQLITE_CON
16e50 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 FIG_LOG is.** pa
16e60 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 ssed through as
16e70 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 the first parame
16e80 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 ter to the appli
16e90 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c cation-defined l
16ea0 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f ogger.** functio
16eb0 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 n whenever that
16ec0 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f function is invo
16ed0 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e ked. ^The secon
16ee0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a d parameter to.*
16ef0 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e * the logger fun
16f00 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 ction is a copy
16f10 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 of the first par
16f20 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f ameter to the co
16f30 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b rresponding.** [
16f40 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 sqlite3_log()] c
16f50 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e all and is inten
16f60 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 ded to be a [res
16f70 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a ult code] or an.
16f80 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 ** [extended res
16f90 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 ult code]. ^The
16fa0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
16fb0 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c passed to the l
16fc0 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 ogger is.** log
16fd0 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f message after fo
16fe0 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 rmatting via [sq
16ff0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 lite3_snprintf()
17000 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 ]..** The SQLite
17010 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 logging interfa
17020 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 ce is not reentr
17030 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 ant; the logger
17040 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 function.** supp
17050 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c lied by the appl
17060 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 ication must not
17070 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 invoke any SQLi
17080 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a te interface..**
17090 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 In a multi-thre
170a0 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e aded application
170b0 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f , the applicatio
170c0 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 n-defined logger
170d0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 .** function mus
170e0 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e t be threadsafe.
170f0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 </dd>.**.** [[S
17100 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 QLITE_CONFIG_URI
17110 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
17120 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e NFIG_URI.** <dd>
17130 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e ^(The SQLITE_CON
17140 46 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 FIG_URI option t
17150 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 akes a single ar
17160 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 gument of type i
17170 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 nt..** If non-ze
17180 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e ro, then URI han
17190 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c dling is globall
171a0 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 y enabled. If th
171b0 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a e parameter is z
171c0 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 ero,.** then URI
171d0 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f handling is glo
171e0 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 bally disabled.)
171f0 5e 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69 ^ ^If URI handli
17200 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a ng is globally.*
17210 2a 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 * enabled, all f
17220 69 6c 65 6e 61 6d 65 73 20 70 61 73 73 65 64 20 ilenames passed
17230 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e to [sqlite3_open
17240 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 ()], [sqlite3_op
17250 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 en_v2()],.** [sq
17260 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 lite3_open16()]
17270 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 or.** specified
17280 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 as part of [ATTA
17290 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 CH] commands are
172a0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 interpreted as
172b0 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 URIs, regardless
172c0 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f .** of whether o
172d0 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 r not the [SQLIT
172e0 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 E_OPEN_URI] flag
172f0 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 is set when the
17300 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e database.** con
17310 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 nection is opene
17320 64 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f d. ^If it is glo
17330 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 bally disabled,
17340 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a filenames are.**
17350 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 only interprete
17360 64 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65 d as URIs if the
17370 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 SQLITE_OPEN_URI
17380 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 flag is set whe
17390 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 n the.** databas
173a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 e connection is
173b0 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 opened. ^(By def
173c0 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 ault, URI handli
173d0 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a ng is globally.*
173e0 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 * disabled. The
173f0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 default value ma
17400 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 y be changed by
17410 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 compiling with t
17420 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 he.** [SQLITE_US
17430 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 E_URI] symbol de
17440 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b fined.)^.**.** [
17450 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 [SQLITE_CONFIG_C
17460 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 OVERING_INDEX_SC
17470 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f AN]] <dt>SQLITE_
17480 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f CONFIG_COVERING_
17490 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 INDEX_SCAN.** <d
174a0 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f d>^The SQLITE_CO
174b0 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e NFIG_COVERING_IN
174c0 44 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 DEX_SCAN option
174d0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 takes a single i
174e0 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 nteger.** argume
174f0 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e 74 65 nt which is inte
17500 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f rpreted as a boo
17510 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f lean in order to
17520 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 enable or disab
17530 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 le.** the use of
17540 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 covering indice
17550 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 s for full table
17560 20 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 scans in the qu
17570 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a ery optimizer..*
17580 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 * ^The default s
17590 65 74 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d etting is determ
175a0 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b ined.** by the [
175b0 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 SQLITE_ALLOW_COV
175c0 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e ERING_INDEX_SCAN
175d0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
175e0 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e ption, or is "on
175f0 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d ".** if that com
17600 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
17610 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 is omitted..**
17620 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64 The ability to d
17630 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f isable the use o
17640 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 f covering indic
17650 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c es for full tabl
17660 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 e scans.** is be
17670 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 cause some incor
17680 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 rectly coded leg
17690 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 acy applications
176a0 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 might malfuncti
176b0 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f on.** when the o
176c0 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 ptimization is e
176d0 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 nabled. Providi
176e0 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 ng the ability t
176f0 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65 o.** disable the
17700 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c optimization al
17710 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 lows the older,
17720 62 75 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f buggy applicatio
17730 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a n code to work.*
17740 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65 * without change
17750 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72 even with newer
17760 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
17770 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c ite..**.** [[SQL
17780 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 ITE_CONFIG_PCACH
17790 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e E]] [[SQLITE_CON
177a0 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a FIG_GETPCACHE]].
177b0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ** <dt>SQLITE_CO
177c0 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 NFIG_PCACHE and
177d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
177e0 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 TPCACHE.** <dd>
177f0 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 These options ar
17800 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 e obsolete and s
17810 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 hould not be use
17820 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a d by new code..*
17830 2a 20 54 68 65 79 20 61 72 65 20 72 65 74 61 69 * They are retai
17840 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 ned for backward
17850 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 s compatibility
17860 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f but are now no-o
17870 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a ps..** </dd>.**.
17880 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
17890 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c IG_SQLLOG]].** <
178a0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
178b0 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 _SQLLOG.** <dd>T
178c0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e his option is on
178d0 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 ly available if
178e0 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c sqlite is compil
178f0 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b ed with the.** [
17900 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 SQLITE_ENABLE_SQ
17910 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 LLOG] pre-proces
17920 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 sor macro define
17930 64 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 67 d. The first arg
17940 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 ument should.**
17950 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 be a pointer to
17960 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 a function of ty
17970 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a pe void(*)(void*
17980 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 ,sqlite3*,const
17990 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 char*, int)..**
179a0 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c The second shoul
179b0 64 20 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f d be of type (vo
179c0 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 id*). The callba
179d0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 ck is invoked by
179e0 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 the library.**
179f0 69 6e 20 74 68 72 65 65 20 73 65 70 61 72 61 74 in three separat
17a00 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c e circumstances,
17a10 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 identified by t
17a20 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 he value passed
17a30 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 as the.** fourth
17a40 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74 parameter. If t
17a50 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
17a60 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74 ter is 0, then t
17a70 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
17a80 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 ection.** passed
17a90 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 as the second a
17aa0 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 rgument has just
17ab0 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 been opened. Th
17ac0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 e third argument
17ad0 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 .** points to a
17ae0 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e buffer containin
17af0 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 g the name of th
17b00 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 e main database
17b10 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 file. If the.**
17b20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
17b30 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20 is 1, then the
17b40 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 SQL statement th
17b50 61 74 20 74 68 65 20 74 68 69 72 64 20 70 61 72 at the third par
17b60 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 ameter.** points
17b70 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65 to has just bee
17b80 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 n executed. Or,
17b90 69 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 if the fourth pa
17ba0 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68 rameter is 2, th
17bb0 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 en.** the connec
17bc0 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65 tion being passe
17bd0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 d as the second
17be0 70 61 72 61 6d 65 74 65 72 20 69 73 20 62 65 69 parameter is bei
17bf0 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a ng closed. The.*
17c00 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 * third paramete
17c10 72 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c r is passed NULL
17c20 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20 In this case.
17c30 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 An example of us
17c40 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 ing this.** conf
17c50 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
17c60 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 can be seen in
17c70 74 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 the "test_sqllog
17c80 2e 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20 .c" source file
17c90 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 in.** the canoni
17ca0 63 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 cal SQLite sourc
17cb0 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a e tree.</dd>.**.
17cc0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
17cd0 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a IG_MMAP_SIZE]].*
17ce0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
17cf0 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a FIG_MMAP_SIZE.**
17d00 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e <dd>^SQLITE_CON
17d10 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 FIG_MMAP_SIZE ta
17d20 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69 kes two 64-bit i
17d30 6e 74 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f nteger (sqlite3_
17d40 69 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a int64) values.**
17d50 20 74 68 61 74 20 61 72 65 20 74 68 65 20 64 65 that are the de
17d60 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 fault mmap size
17d70 6c 69 6d 69 74 20 28 74 68 65 20 64 65 66 61 75 limit (the defau
17d80 6c 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a lt setting for.*
17d90 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 * [PRAGMA mmap_s
17da0 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 ize]) and the ma
17db0 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d ximum allowed mm
17dc0 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a ap size limit..*
17dd0 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 * ^The default s
17de0 65 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 etting can be ov
17df0 65 72 72 69 64 64 65 6e 20 62 79 20 65 61 63 68 erridden by each
17e00 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
17e10 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 tion using.** ei
17e20 74 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41 ther the [PRAGMA
17e30 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d mmap_size] comm
17e40 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 and, or by using
17e50 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the.** [SQLITE_
17e60 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d FCNTL_MMAP_SIZE]
17e70 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 file control.
17e80 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c ^(The maximum al
17e90 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a lowed mmap size.
17ea0 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e ** will be silen
17eb0 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 69 66 tly truncated if
17ec0 20 6e 65 63 65 73 73 61 72 79 20 73 6f 20 74 68 necessary so th
17ed0 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 at it does not e
17ee0 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d xceed the.** com
17ef0 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 pile-time maximu
17f00 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20 m mmap size set
17f10 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 by the.** [SQLIT
17f20 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d E_MAX_MMAP_SIZE]
17f30 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
17f40 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 tion.)^.** ^If e
17f50 69 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74 ither argument t
17f60 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 o this option is
17f70 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 negative, then
17f80 74 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73 that argument is
17f90 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69 .** changed to i
17fa0 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 ts compile-time
17fb0 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b default..**.** [
17fc0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 [SQLITE_CONFIG_W
17fd0 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a IN32_HEAPSIZE]].
17fe0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ** <dt>SQLITE_CO
17ff0 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 NFIG_WIN32_HEAPS
18000 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 IZE.** <dd>^The
18010 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 SQLITE_CONFIG_WI
18020 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 N32_HEAPSIZE opt
18030 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 ion is only avai
18040 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 lable if SQLite
18050 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 is.** compiled f
18060 6f 72 20 57 69 6e 64 6f 77 73 20 77 69 74 68 20 or Windows with
18070 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 the [SQLITE_WIN3
18080 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 2_MALLOC] pre-pr
18090 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a ocessor macro.**
180a0 20 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 defined. ^SQLIT
180b0 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 E_CONFIG_WIN32_H
180c0 45 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20 EAPSIZE takes a
180d0 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 32-bit unsigned
180e0 69 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a integer value.**
180f0 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 that specifies
18100 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 the maximum size
18110 20 6f 66 20 74 68 65 20 63 72 65 61 74 65 64 20 of the created
18120 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 heap..**.** [[SQ
18130 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 LITE_CONFIG_PCAC
18140 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 HE_HDRSZ]].** <d
18150 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
18160 50 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 PCACHE_HDRSZ.**
18170 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f <dd>^The SQLITE_
18180 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 CONFIG_PCACHE_HD
18190 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 RSZ option takes
181a0 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 a single parame
181b0 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 ter which.** is
181c0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
181d0 69 6e 74 65 67 65 72 20 61 6e 64 20 77 72 69 74 integer and writ
181e0 65 73 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 es into that int
181f0 65 67 65 72 20 74 68 65 20 6e 75 6d 62 65 72 20 eger the number
18200 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 of extra.** byte
18210 73 20 70 65 72 20 70 61 67 65 20 72 65 71 75 69 s per page requi
18220 72 65 64 20 66 6f 72 20 65 61 63 68 20 70 61 67 red for each pag
18230 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e e in [SQLITE_CON
18240 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a FIG_PAGECACHE]..
18250 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 ** The amount of
18260 20 65 78 74 72 61 20 73 70 61 63 65 20 72 65 71 extra space req
18270 75 69 72 65 64 20 63 61 6e 20 63 68 61 6e 67 65 uired can change
18280 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 depending on th
18290 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 e compiler,.** t
182a0 61 72 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 arget platform,
182b0 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 and SQLite versi
182c0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 on..**.** [[SQLI
182d0 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d TE_CONFIG_PMASZ]
182e0 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f ].** <dt>SQLITE_
182f0 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 CONFIG_PMASZ.**
18300 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f <dd>^The SQLITE_
18310 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 CONFIG_PMASZ opt
18320 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 ion takes a sing
18330 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 le parameter whi
18340 63 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 ch.** is an unsi
18350 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 gned integer and
18360 20 73 65 74 73 20 74 68 65 20 22 4d 69 6e 69 6d sets the "Minim
18370 75 6d 20 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 um PMA Size" for
18380 20 74 68 65 20 6d 75 6c 74 69 74 68 72 65 61 64 the multithread
18390 65 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 ed.** sorter to
183a0 74 68 61 74 20 69 6e 74 65 67 65 72 2e 20 20 54 that integer. T
183b0 68 65 20 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d he default minim
183c0 75 6d 20 50 4d 41 20 53 69 7a 65 20 69 73 20 73 um PMA Size is s
183d0 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 et by the.** [SQ
183e0 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 LITE_SORTER_PMAS
183f0 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 Z] compile-time
18400 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 option. New thr
18410 65 61 64 73 20 61 72 65 20 6c 61 75 6e 63 68 65 eads are launche
18420 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 d.** to help wit
18430 68 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e h sort operation
18440 73 20 77 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 s when multithre
18450 61 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 aded sorting.**
18460 69 73 20 65 6e 61 62 6c 65 64 20 28 75 73 69 6e is enabled (usin
18470 67 20 74 68 65 20 5b 50 52 41 47 4d 41 20 74 68 g the [PRAGMA th
18480 72 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 reads] command)
18490 61 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f and the amount o
184a0 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 f content.** to
184b0 62 65 20 73 6f 72 74 65 64 20 65 78 63 65 65 64 be sorted exceed
184c0 73 20 74 68 65 20 70 61 67 65 20 73 69 7a 65 20 s the page size
184d0 74 69 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 times the minimu
184e0 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 m of the.** [PRA
184f0 47 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 GMA cache_size]
18500 73 65 74 74 69 6e 67 20 61 6e 64 20 74 68 69 73 setting and this
18510 20 76 61 6c 75 65 2e 0a 2a 2a 20 3c 2f 64 6c 3e value..** </dl>
18520 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
18530 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 TE_CONFIG_SINGLE
18540 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 THREAD 1 /* ni
18550 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c l */.#define SQL
18560 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 ITE_CONFIG_MULTI
18570 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e THREAD 2 /* n
18580 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 il */.#define SQ
18590 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 LITE_CONFIG_SERI
185a0 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 ALIZED 3 /*
185b0 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nil */.#define S
185c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c QLITE_CONFIG_MAL
185d0 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a LOC 4 /*
185e0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 sqlite3_mem_met
185f0 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 hods* */.#define
18600 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 SQLITE_CONFIG_G
18610 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 ETMALLOC 5
18620 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d /* sqlite3_mem_m
18630 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 ethods* */.#defi
18640 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
18650 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36 _SCRATCH 6
18660 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 /* void*, int
18670 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 sz, int N */.#de
18680 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
18690 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 IG_PAGECACHE
186a0 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 7 /* void*, in
186b0 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 t sz, int N */.#
186c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
186d0 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 NFIG_HEAP
186e0 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 8 /* void*,
186f0 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d int nByte, int m
18700 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 in */.#define SQ
18710 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 LITE_CONFIG_MEMS
18720 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 TATUS 9 /*
18730 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 boolean */.#defi
18740 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
18750 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30 _MUTEX 10
18760 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 /* sqlite3_mut
18770 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 ex_methods* */.#
18780 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
18790 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 NFIG_GETMUTEX
187a0 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 11 /* sqlite3
187b0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 _mutex_methods*
187c0 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 */./* previously
187d0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 SQLITE_CONFIG_C
187e0 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 HUNKALLOC 12 whi
187f0 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 ch is now unused
18800 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 . */ .#define SQ
18810 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b LITE_CONFIG_LOOK
18820 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 ASIDE 13 /*
18830 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 int int */.#defi
18840 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
18850 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34 _PCACHE 14
18860 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 /* no-op */.#d
18870 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
18880 46 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 FIG_GETPCACHE
18890 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 15 /* no-op */
188a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
188b0 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 CONFIG_LOG
188c0 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 16 /* xFunc
188d0 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 , void* */.#defi
188e0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
188f0 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 31 37 _URI 17
18900 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 /* int */.#def
18910 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
18920 47 5f 50 43 41 43 48 45 32 20 20 20 20 20 20 31 G_PCACHE2 1
18930 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 8 /* sqlite3_pc
18940 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a ache_methods2* *
18950 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
18960 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 _CONFIG_GETPCACH
18970 45 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 E2 19 /* sqli
18980 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f te3_pcache_metho
18990 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ds2* */.#define
189a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f SQLITE_CONFIG_CO
189b0 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 VERING_INDEX_SCA
189c0 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a N 20 /* int */.
189d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
189e0 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 ONFIG_SQLLOG
189f0 20 20 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 21 /* xSqllo
18a00 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 g, void* */.#def
18a10 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
18a20 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 G_MMAP_SIZE 2
18a30 32 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 2 /* sqlite3_in
18a40 74 36 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 t64, sqlite3_int
18a50 36 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 64 */.#define SQ
18a60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 LITE_CONFIG_WIN3
18a70 32 5f 48 45 41 50 53 49 5a 45 20 20 20 20 20 20 2_HEAPSIZE
18a80 32 33 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 23 /* int nByte
18a90 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
18aa0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 TE_CONFIG_PCACHE
18ab0 5f 48 44 52 53 5a 20 20 20 20 20 20 20 20 32 34 _HDRSZ 24
18ac0 20 20 2f 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f /* int *psz */
18ad0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
18ae0 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 CONFIG_PMASZ
18af0 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 2f 25 /
18b00 2a 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 * unsigned int s
18b10 7a 50 6d 61 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 zPma */../*.** C
18b20 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 API3REF: Databas
18b30 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e e Connection Con
18b40 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f figuration Optio
18b50 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 ns.**.** These c
18b60 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 onstants are the
18b70 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 available integ
18b80 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e er configuration
18b90 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a options that.**
18ba0 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 can be passed a
18bb0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 s the second arg
18bc0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 ument to the [sq
18bd0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 lite3_db_config(
18be0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a )] interface..**
18bf0 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 .** New configur
18c00 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 ation options ma
18c10 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 y be added in fu
18c20 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 ture releases of
18c30 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 SQLite..** Exis
18c40 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 ting configurati
18c50 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 on options might
18c60 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 be discontinued
18c70 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a . Applications.
18c80 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 ** should check
18c90 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 the return code
18ca0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 from [sqlite3_db
18cb0 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 _config()] to ma
18cc0 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 ke sure that.**
18cd0 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e the call worked.
18ce0 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f ^The [sqlite3_
18cf0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 db_config()] int
18d00 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 erface will retu
18d10 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f rn a.** non-zero
18d20 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 [error code] if
18d30 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 a discontinued
18d40 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 or unsupported c
18d50 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
18d60 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 ion.** is invoke
18d70 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a d..**.** <dl>.**
18d80 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f <dt>SQLITE_DBCO
18d90 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f NFIG_LOOKASIDE</
18da0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 dt>.** <dd> ^Thi
18db0 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 s option takes t
18dc0 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 hree additional
18dd0 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 arguments that d
18de0 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a etermine the .**
18df0 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f [lookaside memo
18e00 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f ry allocator] co
18e10 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 nfiguration for
18e20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
18e30 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 nnection]..** ^T
18e40 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
18e50 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72 t (the third par
18e60 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 ameter to [sqlit
18e70 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 e3_db_config()]
18e80 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 is a.** pointer
18e90 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 to a memory buff
18ea0 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f er to use for lo
18eb0 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a okaside memory..
18ec0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 ** ^The first ar
18ed0 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65 gument after the
18ee0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 SQLITE_DBCONFIG
18ef0 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a _LOOKASIDE verb.
18f00 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 ** may be NULL i
18f10 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51 4c n which case SQL
18f20 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 ite will allocat
18f30 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 e the.** lookasi
18f40 64 65 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 de buffer itself
18f50 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
18f60 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 malloc()]. ^The
18f70 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
18f80 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f is the.** size o
18f90 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 f each lookaside
18fa0 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e buffer slot. ^
18fb0 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 The third argume
18fc0 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 nt is the number
18fd0 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 of.** slots. T
18fe0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 he size of the b
18ff0 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 uffer in the fir
19000 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 st argument must
19010 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61 6e be greater than
19020 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 .** or equal to
19030 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 the product of t
19040 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 he second and th
19050 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 ird arguments.
19060 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 The buffer.** mu
19070 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f st be aligned to
19080 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 an 8-byte bound
19090 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65 ary. ^If the se
190a0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f cond argument to
190b0 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e .** SQLITE_DBCON
190c0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 FIG_LOOKASIDE is
190d0 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 not a multiple
190e0 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65 of 8, it is inte
190f0 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 rnally.** rounde
19100 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 d down to the ne
19110 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 xt smaller multi
19120 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 ple of 8. ^(The
19130 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 lookaside memor
19140 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 y.** configurati
19150 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 on for a databas
19160 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e e connection can
19170 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64 only be changed
19180 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f when that.** co
19190 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 nnection is not
191a0 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 currently using
191b0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 lookaside memory
191c0 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f , or in other wo
191d0 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 rds.** when the
191e0 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20 "current value"
191f0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b returned by.** [
19200 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 sqlite3_db_statu
19210 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e s](D,[SQLITE_CON
19220 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e FIG_LOOKASIDE],.
19230 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 ..) is zero..**
19240 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 Any attempt to c
19250 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 hange the lookas
19260 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 ide memory confi
19270 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f guration when lo
19280 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 okaside.** memor
19290 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76 y is in use leav
192a0 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 es the configura
192b0 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 tion unchanged a
192c0 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b nd returns .** [
192d0 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c SQLITE_BUSY].)^<
192e0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
192f0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 QLITE_DBCONFIG_E
19300 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a NABLE_FKEY</dt>.
19310 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 ** <dd> ^This op
19320 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 tion is used to
19330 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c enable or disabl
19340 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e e the enforcemen
19350 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e t of.** [foreign
19360 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 key constraints
19370 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64 ]. There should
19380 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e be two addition
19390 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a al arguments..**
193a0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
193b0 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 ent is an intege
193c0 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 r which is 0 to
193d0 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 disable FK enfor
193e0 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 cement,.** posit
193f0 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b ive to enable FK
19400 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 enforcement or
19410 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 negative to leav
19420 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 e FK enforcement
19430 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 .** unchanged.
19440 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
19450 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 eter is a pointe
19460 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 r to an integer
19470 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 into which.** is
19480 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 written 0 or 1
19490 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 to indicate whet
194a0 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 her FK enforceme
194b0 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a nt is off or on.
194c0 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 ** following thi
194d0 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 s call. The sec
194e0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 ond parameter ma
194f0 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e y be a NULL poin
19500 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 ter, in.** which
19510 20 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66 case the FK enf
19520 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 orcement setting
19530 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 is not reported
19540 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a back. </dd>.**.
19550 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 ** <dt>SQLITE_DB
19560 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 CONFIG_ENABLE_TR
19570 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 IGGER</dt>.** <d
19580 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 d> ^This option
19590 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c is used to enabl
195a0 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52 e or disable [CR
195b0 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 EATE TRIGGER | t
195c0 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 riggers]..** The
195d0 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f re should be two
195e0 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 additional argu
195f0 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 ments..** The fi
19600 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 rst argument is
19610 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 an integer which
19620 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 is 0 to disable
19630 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f triggers,.** po
19640 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 sitive to enable
19650 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67 triggers or neg
19660 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 ative to leave t
19670 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 he setting uncha
19680 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 nged..** The sec
19690 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ond parameter is
196a0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
196b0 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 integer into wh
196c0 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 ich.** is writte
196d0 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 n 0 or 1 to indi
196e0 63 61 74 65 20 77 68 65 74 68 65 72 20 74 72 69 cate whether tri
196f0 67 67 65 72 73 20 61 72 65 20 64 69 73 61 62 6c ggers are disabl
19700 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a ed or enabled.**
19710 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 following this
19720 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e call. The secon
19730 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 d parameter may
19740 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 be a NULL pointe
19750 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 r, in.** which c
19760 61 73 65 20 74 68 65 20 74 72 69 67 67 65 72 20 ase the trigger
19770 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 setting is not r
19780 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f eported back. </
19790 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a dd>.**.** </dl>.
197a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
197b0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 E_DBCONFIG_LOOKA
197c0 53 49 44 45 20 20 20 20 20 20 20 31 30 30 31 20 SIDE 1001
197d0 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e /* void* int in
197e0 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c t */.#define SQL
197f0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 ITE_DBCONFIG_ENA
19800 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31 30 30 BLE_FKEY 100
19810 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2 /* int int* *
19820 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
19830 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 _DBCONFIG_ENABLE
19840 5f 54 52 49 47 47 45 52 20 20 31 30 30 33 20 20 _TRIGGER 1003
19850 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a /* int int* */..
19860 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
19870 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 Enable Or Disab
19880 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 le Extended Resu
19890 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 lt Codes.** METH
198a0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a OD: sqlite3.**.*
198b0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 * ^The sqlite3_e
198c0 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 xtended_result_c
198d0 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 odes() routine e
198e0 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c nables or disabl
198f0 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e es the.** [exten
19900 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
19910 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c ] feature of SQL
19920 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 ite. ^The extend
19930 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 ed result.** cod
19940 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 es are disabled
19950 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 by default for h
19960 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 istorical compat
19970 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49 ibility..*/.SQLI
19980 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
19990 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
199a0 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 3_extended_resul
199b0 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a t_codes(sqlite3*
199c0 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f , int onoff);../
199d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c *.** CAPI3REF: L
199e0 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 ast Insert Rowid
199f0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
19a00 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 te3.**.** ^Each
19a10 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53 51 entry in most SQ
19a20 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65 78 63 Lite tables (exc
19a30 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55 54 ept for [WITHOUT
19a40 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29 0a ROWID] tables).
19a50 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 ** has a unique
19a60 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 64-bit signed.**
19a70 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c integer key cal
19a80 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c led the [ROWID |
19a90 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 "rowid"]. ^The
19aa0 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 rowid is always
19ab0 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 available.** as
19ac0 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f an undeclared co
19ad0 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 lumn named ROWID
19ae0 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 , OID, or _ROWID
19af0 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f _ as long as tho
19b00 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 se.** names are
19b10 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 not also used by
19b20 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c explicitly decl
19b30 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 ared columns. ^I
19b40 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 f.** the table h
19b50 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 as a column of t
19b60 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 ype [INTEGER PRI
19b70 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 MARY KEY] then t
19b80 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 hat column.** is
19b90 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 another alias f
19ba0 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a or the rowid..**
19bb0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
19bc0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 _last_insert_row
19bd0 69 64 28 44 29 20 69 6e 74 65 72 66 61 63 65 20 id(D) interface
19be0 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 returns the [row
19bf0 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6d id] of the .** m
19c00 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63 63 65 ost recent succe
19c10 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 ssful [INSERT] i
19c20 6e 74 6f 20 61 20 72 6f 77 69 64 20 74 61 62 6c nto a rowid tabl
19c30 65 20 6f 72 20 5b 76 69 72 74 75 61 6c 20 74 61 e or [virtual ta
19c40 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 ble].** on datab
19c50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 ase connection D
19c60 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73 20 69 6e ..** ^Inserts in
19c70 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 to [WITHOUT ROWI
19c80 44 5d 20 74 61 62 6c 65 73 20 61 72 65 20 6e 6f D] tables are no
19c90 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a 2a 20 5e t recorded..** ^
19ca0 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c If no successful
19cb0 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f 20 [INSERT]s into
19cc0 72 6f 77 69 64 20 74 61 62 6c 65 73 0a 2a 2a 20 rowid tables.**
19cd0 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 have ever occurr
19ce0 65 64 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 ed on the databa
19cf0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c se connection D,
19d00 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 .** then sqlite
19d10 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 3_last_insert_ro
19d20 77 69 64 28 44 29 20 72 65 74 75 72 6e 73 20 7a wid(D) returns z
19d30 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 ero..**.** ^(If
19d40 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 an [INSERT] occu
19d50 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 rs within a trig
19d60 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20 61 20 ger or within a
19d70 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a [virtual table].
19d80 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 ** method, then
19d90 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c this routine wil
19da0 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f l return the [ro
19db0 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 wid] of the inse
19dc0 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c rted.** row as l
19dd0 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67 ong as the trigg
19de0 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 er or virtual ta
19df0 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20 72 75 ble method is ru
19e00 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e nning..** But on
19e10 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f ce the trigger o
19e20 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 r virtual table
19e30 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74 68 65 method ends, the
19e40 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
19e50 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 .** by this rout
19e60 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 77 ine reverts to w
19e70 68 61 74 20 69 74 20 77 61 73 20 62 65 66 6f 72 hat it was befor
19e80 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 e the trigger or
19e90 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c virtual.** tabl
19ea0 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e 29 e method began.)
19eb0 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 ^.**.** ^An [INS
19ec0 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 ERT] that fails
19ed0 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 due to a constra
19ee0 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 int violation is
19ef0 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 not a.** succes
19f00 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e sful [INSERT] an
19f10 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 d does not chang
19f20 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 e the value retu
19f30 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 rned by this.**
19f40 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 routine. ^Thus
19f50 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 INSERT OR FAIL,
19f60 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 INSERT OR IGNORE
19f70 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c , INSERT OR ROLL
19f80 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 BACK,.** and INS
19f90 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b ERT OR ABORT mak
19fa0 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 e no changes to
19fb0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
19fc0 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 of this.** rout
19fd0 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 ine when their i
19fe0 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 nsertion fails.
19ff0 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f ^(When INSERT O
1a000 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 R REPLACE.** enc
1a010 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 ounters a constr
1a020 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 aint violation,
1a030 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c it does not fail
1a040 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 . The.** INSERT
1a050 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f continues to co
1a060 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 mpletion after d
1a070 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 eleting rows tha
1a080 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 t caused.** the
1a090 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c constraint probl
1a0a0 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 em so INSERT OR
1a0b0 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 REPLACE will alw
1a0c0 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 ays change.** th
1a0d0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f e return value o
1a0e0 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 f this interface
1a0f0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 .)^.**.** ^For t
1a100 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 he purposes of t
1a110 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 his routine, an
1a120 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 [INSERT] is cons
1a130 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 idered to.** be
1a140 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 successful even
1a150 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75 if it is subsequ
1a160 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 ently rolled bac
1a170 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 k..**.** This fu
1a180 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 nction is access
1a190 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 ible to SQL stat
1a1a0 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a ements via the.*
1a1b0 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 * [last_insert_r
1a1c0 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 owid() SQL funct
1a1d0 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 ion]..**.** If a
1a1e0 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 separate thread
1a1f0 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 performs a new
1a200 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 [INSERT] on the
1a210 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 same.** database
1a220 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c connection whil
1a230 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c e the [sqlite3_l
1a240 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 ast_insert_rowid
1a250 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 ()].** function
1a260 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 is running and t
1a270 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 hus changes the
1a280 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 last insert [row
1a290 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 id],.** then the
1a2a0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
1a2b0 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 by [sqlite3_last
1a2c0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d _insert_rowid()]
1a2d0 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 is.** unpredict
1a2e0 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e able and might n
1a2f0 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 ot equal either
1a300 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e the old or the n
1a310 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 ew.** last inser
1a320 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 t [rowid]..*/.SQ
1a330 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 LITE_API sqlite3
1a340 5f 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 54 _int64 SQLITE_ST
1a350 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6c 61 DCALL sqlite3_la
1a360 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 st_insert_rowid(
1a370 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a sqlite3*);../*.*
1a380 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e * CAPI3REF: Coun
1a390 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 t The Number Of
1a3a0 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a Rows Modified.**
1a3b0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
1a3c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e .**.** ^This fun
1a3d0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 ction returns th
1a3e0 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 e number of rows
1a3f0 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 72 modified, inser
1a400 74 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 ted or.** delete
1a410 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 d by the most re
1a420 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 cently completed
1a430 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 INSERT, UPDATE
1a440 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 or DELETE.** sta
1a450 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 64 61 tement on the da
1a460 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1a470 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 n specified by t
1a480 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 he only paramete
1a490 72 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69 6e 67 r..** ^Executing
1a4a0 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 any other type
1a4b0 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 of SQL statement
1a4c0 20 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79 does not modify
1a4d0 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 the value.** re
1a4e0 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 turned by this f
1a4f0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e unction..**.** ^
1a500 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64 Only changes mad
1a510 65 20 64 69 72 65 63 74 6c 79 20 62 79 20 74 68 e directly by th
1a520 65 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 e INSERT, UPDATE
1a530 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 or DELETE state
1a540 6d 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 ment are.** cons
1a550 69 64 65 72 65 64 20 2d 20 61 75 78 69 6c 69 61 idered - auxilia
1a560 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 ry changes cause
1a570 64 20 62 79 20 5b 43 52 45 41 54 45 20 54 52 49 d by [CREATE TRI
1a580 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d GGER | triggers]
1a590 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b , .** [foreign k
1a5a0 65 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72 20 5b ey actions] or [
1a5b0 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 REPLACE] constra
1a5c0 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 int resolution a
1a5d0 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a re not counted..
1a5e0 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74 ** .** Changes t
1a5f0 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 o a view that ar
1a600 65 20 69 6e 74 65 72 63 65 70 74 65 64 20 62 79 e intercepted by
1a610 20 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20 4f 46 .** [INSTEAD OF
1a620 20 74 72 69 67 67 65 72 20 7c 20 49 4e 53 54 45 trigger | INSTE
1a630 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 5d 20 AD OF triggers]
1a640 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e are not counted.
1a650 20 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20 ^The value .**
1a660 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 returned by sqli
1a670 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6d te3_changes() im
1a680 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65 72 20 mediately after
1a690 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 an INSERT, UPDAT
1a6a0 45 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 45 20 E or .** DELETE
1a6b0 73 74 61 74 65 6d 65 6e 74 20 72 75 6e 20 6f 6e statement run on
1a6c0 20 61 20 76 69 65 77 20 69 73 20 61 6c 77 61 79 a view is alway
1a6d0 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 s zero. Only cha
1a6e0 6e 67 65 73 20 6d 61 64 65 20 74 6f 20 72 65 61 nges made to rea
1a6f0 6c 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61 72 65 l .** tables are
1a700 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 counted..**.**
1a710 54 68 69 6e 67 73 20 61 72 65 20 6d 6f 72 65 20 Things are more
1a720 63 6f 6d 70 6c 69 63 61 74 65 64 20 69 66 20 74 complicated if t
1a730 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 he sqlite3_chang
1a740 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 es() function is
1a750 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 77 68 69 .** executed whi
1a760 6c 65 20 61 20 74 72 69 67 67 65 72 20 70 72 6f le a trigger pro
1a770 67 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e 67 2e gram is running.
1a780 20 54 68 69 73 20 6d 61 79 20 68 61 70 70 65 6e This may happen
1a790 20 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 if the.** progr
1a7a0 61 6d 20 75 73 65 73 20 74 68 65 20 5b 63 68 61 am uses the [cha
1a7b0 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 nges() SQL funct
1a7c0 69 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f 6d 65 ion], or if some
1a7d0 20 6f 74 68 65 72 20 63 61 6c 6c 62 61 63 6b 0a other callback.
1a7e0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e 76 6f ** function invo
1a7f0 6b 65 73 20 73 71 6c 69 74 65 33 5f 63 68 61 6e kes sqlite3_chan
1a800 67 65 73 28 29 20 64 69 72 65 63 74 6c 79 2e 20 ges() directly.
1a810 45 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 Essentially:.**
1a820 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c .** <ul>.** <l
1a830 69 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e 74 65 i> ^(Before ente
1a840 72 69 6e 67 20 61 20 74 72 69 67 67 65 72 20 70 ring a trigger p
1a850 72 6f 67 72 61 6d 20 74 68 65 20 76 61 6c 75 65 rogram the value
1a860 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 returned by.**
1a870 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 sqlite3_c
1a880 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f hanges() functio
1a890 6e 20 69 73 20 73 61 76 65 64 2e 20 41 66 74 65 n is saved. Afte
1a8a0 72 20 74 68 65 20 74 72 69 67 67 65 72 20 70 72 r the trigger pr
1a8b0 6f 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20 20 20 ogram .**
1a8c0 20 68 61 73 20 66 69 6e 69 73 68 65 64 2c 20 74 has finished, t
1a8d0 68 65 20 6f 72 69 67 69 6e 61 6c 20 76 61 6c 75 he original valu
1a8e0 65 20 69 73 20 72 65 73 74 6f 72 65 64 2e 29 5e e is restored.)^
1a8f0 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e .** .** <li> ^
1a900 28 57 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 (Within a trigge
1a910 72 20 70 72 6f 67 72 61 6d 20 65 61 63 68 20 49 r program each I
1a920 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 61 6e NSERT, UPDATE an
1a930 64 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20 20 20 d DELETE .**
1a940 20 20 20 20 73 74 61 74 65 6d 65 6e 74 20 73 65 statement se
1a950 74 73 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 ts the value ret
1a960 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 urned by sqlite3
1a970 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 _changes() .**
1a980 20 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d 70 6c upon compl
1a990 65 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e etion as normal.
1a9a0 20 4f 66 20 63 6f 75 72 73 65 2c 20 74 68 69 73 Of course, this
1a9b0 20 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f 74 20 value will not
1a9c0 69 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20 20 20 include .**
1a9d0 20 20 20 61 6e 79 20 63 68 61 6e 67 65 73 20 70 any changes p
1a9e0 65 72 66 6f 72 6d 65 64 20 62 79 20 73 75 62 2d erformed by sub-
1a9f0 74 72 69 67 67 65 72 73 2c 20 61 73 20 74 68 65 triggers, as the
1aa00 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 sqlite3_changes
1aa10 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 76 61 () .** va
1aa20 6c 75 65 20 77 69 6c 6c 20 62 65 20 73 61 76 65 lue will be save
1aa30 64 20 61 6e 64 20 72 65 73 74 6f 72 65 64 20 61 d and restored a
1aa40 66 74 65 72 20 65 61 63 68 20 73 75 62 2d 74 72 fter each sub-tr
1aa50 69 67 67 65 72 20 68 61 73 20 72 75 6e 2e 29 5e igger has run.)^
1aa60 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a .** </ul>.** .**
1aa70 20 5e 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 ^This means tha
1aa80 74 20 69 66 20 74 68 65 20 63 68 61 6e 67 65 73 t if the changes
1aa90 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 () SQL function
1aaa0 28 6f 72 20 73 69 6d 69 6c 61 72 29 20 69 73 20 (or similar) is
1aab0 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 used.** by the f
1aac0 69 72 73 74 20 49 4e 53 45 52 54 2c 20 55 50 44 irst INSERT, UPD
1aad0 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 ATE or DELETE st
1aae0 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 atement within a
1aaf0 20 74 72 69 67 67 65 72 2c 20 69 74 20 0a 2a 2a trigger, it .**
1ab00 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c returns the val
1ab10 75 65 20 61 73 20 73 65 74 20 77 68 65 6e 20 74 ue as set when t
1ab20 68 65 20 63 61 6c 6c 69 6e 67 20 73 74 61 74 65 he calling state
1ab30 6d 65 6e 74 20 62 65 67 61 6e 20 65 78 65 63 75 ment began execu
1ab40 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 ting..** ^If it
1ab50 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 73 is used by the s
1ab60 65 63 6f 6e 64 20 6f 72 20 73 75 62 73 65 71 75 econd or subsequ
1ab70 65 6e 74 20 73 75 63 68 20 73 74 61 74 65 6d 65 ent such stateme
1ab80 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 nt within a trig
1ab90 67 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c ger .** program,
1aba0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 the value retur
1abb0 6e 65 64 20 72 65 66 6c 65 63 74 73 20 74 68 65 ned reflects the
1abc0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 number of rows
1abd0 6d 6f 64 69 66 69 65 64 20 62 79 20 74 68 65 20 modified by the
1abe0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 49 4e 53 .** previous INS
1abf0 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 ERT, UPDATE or D
1ac00 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 ELETE statement
1ac10 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 within the same
1ac20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 trigger..**.** S
1ac30 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c ee also the [sql
1ac40 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 ite3_total_chang
1ac50 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c es()] interface,
1ac60 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 the.** [count_c
1ac70 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 hanges pragma],
1ac80 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 and the [changes
1ac90 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d () SQL function]
1aca0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 ..**.** If a sep
1acb0 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b arate thread mak
1acc0 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 es changes on th
1acd0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 e same database
1ace0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 connection.** wh
1acf0 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 ile [sqlite3_cha
1ad00 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 nges()] is runni
1ad10 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 ng then the valu
1ad20 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 e returned.** is
1ad30 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 unpredictable a
1ad40 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 nd not meaningfu
1ad50 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 l..*/.SQLITE_API
1ad60 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
1ad70 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 68 61 6e ALL sqlite3_chan
1ad80 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a ges(sqlite3*);..
1ad90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1ada0 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 Total Number Of
1adb0 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a Rows Modified.**
1adc0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
1add0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e .**.** ^This fun
1ade0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 ction returns th
1adf0 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f e total number o
1ae00 66 20 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c f rows inserted,
1ae10 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 modified or.**
1ae20 64 65 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b deleted by all [
1ae30 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 INSERT], [UPDATE
1ae40 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 ] or [DELETE] st
1ae50 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 atements complet
1ae60 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 ed.** since the
1ae70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1ae80 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 ion was opened,
1ae90 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 including those
1aea0 65 78 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 executed as.** p
1aeb0 61 72 74 20 6f 66 20 74 72 69 67 67 65 72 20 70 art of trigger p
1aec0 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 rograms. ^Execut
1aed0 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 ing any other ty
1aee0 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d pe of SQL statem
1aef0 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 ent.** does not
1af00 61 66 66 65 63 74 20 74 68 65 20 76 61 6c 75 65 affect the value
1af10 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c returned by sql
1af20 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 ite3_total_chang
1af30 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 es()..** .** ^Ch
1af40 61 6e 67 65 73 20 6d 61 64 65 20 61 73 20 70 61 anges made as pa
1af50 72 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b rt of [foreign k
1af60 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 ey actions] are
1af70 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a included in the.
1af80 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 ** count, but th
1af90 6f 73 65 20 6d 61 64 65 20 61 73 20 70 61 72 74 ose made as part
1afa0 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 of REPLACE cons
1afb0 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f traint resolutio
1afc0 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 n are.** not. ^C
1afd0 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 hanges to a view
1afe0 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 that are interc
1aff0 65 70 74 65 64 20 62 79 20 49 4e 53 54 45 41 44 epted by INSTEAD
1b000 20 4f 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a OF triggers .**
1b010 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 are not counted
1b020 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73 ..** .** See als
1b030 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 o the [sqlite3_c
1b040 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 hanges()] interf
1b050 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 ace, the.** [cou
1b060 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d nt_changes pragm
1b070 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 a], and the [tot
1b080 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c al_changes() SQL
1b090 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a function]..**.*
1b0a0 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 * If a separate
1b0b0 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 thread makes cha
1b0c0 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 nges on the same
1b0d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
1b0e0 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 tion.** while [s
1b0f0 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 qlite3_total_cha
1b100 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 nges()] is runni
1b110 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 ng then the valu
1b120 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 e.** returned is
1b130 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 unpredictable a
1b140 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 nd not meaningfu
1b150 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 l..*/.SQLITE_API
1b160 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
1b170 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 ALL sqlite3_tota
1b180 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 l_changes(sqlite
1b190 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 3*);../*.** CAPI
1b1a0 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 3REF: Interrupt
1b1b0 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 A Long-Running Q
1b1c0 75 65 72 79 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 uery.** METHOD:
1b1d0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 sqlite3.**.** ^T
1b1e0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 his function cau
1b1f0 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 ses any pending
1b200 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 database operati
1b210 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a on to abort and.
1b220 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 ** return at its
1b230 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 earliest opport
1b240 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 unity. This rout
1b250 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 ine is typically
1b260 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 .** called in re
1b270 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 sponse to a user
1b280 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 action such as
1b290 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c pressing "Cancel
1b2a0 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 ".** or Ctrl-C w
1b2b0 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61 here the user wa
1b2c0 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 nts a long query
1b2d0 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 operation to ha
1b2e0 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c lt.** immediatel
1b2f0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 y..**.** ^It is
1b300 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 safe to call thi
1b310 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 s routine from a
1b320 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e thread differen
1b330 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 t from the.** th
1b340 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72 read that is cur
1b350 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 rently running t
1b360 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 he database oper
1b370 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a ation. But it.*
1b380 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f * is not safe to
1b390 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 call this routi
1b3a0 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 ne with a [datab
1b3b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
1b3c0 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 that.** is close
1b3d0 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 d or might close
1b3e0 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f before sqlite3_
1b3f0 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75 interrupt() retu
1b400 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 rns..**.** ^If a
1b410 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 n SQL operation
1b420 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 is very nearly f
1b430 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74 inished at the t
1b440 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 ime when.** sqli
1b450 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 te3_interrupt()
1b460 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 is called, then
1b470 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 it might not hav
1b480 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 e an opportunity
1b490 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 .** to be interr
1b4a0 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 upted and might
1b4b0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 continue to comp
1b4c0 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 letion..**.** ^A
1b4d0 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 n SQL operation
1b4e0 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 that is interrup
1b4f0 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 ted will return
1b500 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 [SQLITE_INTERRUP
1b510 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 T]..** ^If the i
1b520 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f nterrupted SQL o
1b530 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 peration is an I
1b540 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f NSERT, UPDATE, o
1b550 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 r DELETE.** that
1b560 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 is inside an ex
1b570 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 plicit transacti
1b580 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 on, then the ent
1b590 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a ire transaction.
1b5a0 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 ** will be rolle
1b5b0 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 d back automatic
1b5c0 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ally..**.** ^The
1b5d0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
1b5e0 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e pt(D) call is in
1b5f0 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c effect until al
1b600 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e l currently runn
1b610 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 ing.** SQL state
1b620 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 ments on [databa
1b630 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 se connection] D
1b640 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 complete. ^Any
1b650 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 new SQL stateme
1b660 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 nts.** that are
1b670 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 started after th
1b680 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 e sqlite3_interr
1b690 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 upt() call and b
1b6a0 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 efore the .** ru
1b6b0 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 nning statements
1b6c0 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 reaches zero ar
1b6d0 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 e interrupted as
1b6e0 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65 if they had bee
1b6f0 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 n.** running pri
1b700 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 or to the sqlite
1b710 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 3_interrupt() ca
1b720 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 ll. ^New SQL st
1b730 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 atements.** that
1b740 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 are started aft
1b750 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 er the running s
1b760 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 tatement count r
1b770 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a eaches zero are.
1b780 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 ** not effected
1b790 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 by the sqlite3_i
1b7a0 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e nterrupt()..** ^
1b7b0 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 A call to sqlite
1b7c0 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 3_interrupt(D) t
1b7d0 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 hat occurs when
1b7e0 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e there are no run
1b7f0 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 ning.** SQL stat
1b800 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f ements is a no-o
1b810 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 p and has no eff
1b820 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 ect on SQL state
1b830 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 ments.** that ar
1b840 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 e started after
1b850 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 the sqlite3_inte
1b860 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 rrupt() call ret
1b870 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 urns..**.** If t
1b880 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
1b890 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 ection closes wh
1b8a0 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 ile [sqlite3_int
1b8b0 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 errupt()].** is
1b8c0 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 running then bad
1b8d0 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b things will lik
1b8e0 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53 ely happen..*/.S
1b8f0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 QLITE_API void S
1b900 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
1b910 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
1b920 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a sqlite3*);../*.*
1b930 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 * CAPI3REF: Dete
1b940 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 rmine If An SQL
1b950 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d Statement Is Com
1b960 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 plete.**.** Thes
1b970 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 e routines are u
1b980 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d seful during com
1b990 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 mand-line input
1b9a0 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 to determine if
1b9b0 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 the.** currently
1b9c0 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 entered text se
1b9d0 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f ems to form a co
1b9e0 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 mplete SQL state
1b9f0 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 ment or.** if ad
1ba00 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 ditional input i
1ba10 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 s needed before
1ba20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 sending the text
1ba30 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 into.** SQLite
1ba40 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 for parsing. ^T
1ba50 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 hese routines re
1ba60 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e turn 1 if the in
1ba70 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 put string.** ap
1ba80 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f pears to be a co
1ba90 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 mplete SQL state
1baa0 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d ment. ^A statem
1bab0 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f ent is judged to
1bac0 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 be.** complete
1bad0 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 if it ends with
1bae0 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 a semicolon toke
1baf0 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 n and is not a p
1bb00 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 refix of a.** we
1bb10 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 ll-formed CREATE
1bb20 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 TRIGGER stateme
1bb30 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 nt. ^Semicolons
1bb40 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 that are embedd
1bb50 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 ed within.** str
1bb60 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 ing literals or
1bb70 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 quoted identifie
1bb80 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 r names or comme
1bb90 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 nts are not.** i
1bba0 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e ndependent token
1bbb0 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74 s (they are part
1bbc0 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e of the token in
1bbd0 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a which they are.
1bbe0 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 ** embedded) and
1bbf0 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 thus do not cou
1bc00 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e nt as a statemen
1bc10 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e t terminator. ^
1bc20 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e Whitespace.** an
1bc30 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 d comments that
1bc40 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c follow the final
1bc50 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 semicolon are i
1bc60 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 gnored..**.** ^T
1bc70 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 hese routines re
1bc80 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 turn 0 if the st
1bc90 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d atement is incom
1bca0 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a plete. ^If a.**
1bcb0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
1bcc0 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 on fails, then S
1bcd0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 QLITE_NOMEM is r
1bce0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e eturned..**.** ^
1bcf0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 These routines d
1bd00 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 o not parse the
1bd10 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 SQL statements t
1bd20 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 hus.** will not
1bd30 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 detect syntactic
1bd40 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 ally incorrect S
1bd50 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 QL..**.** ^(If S
1bd60 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 QLite has not be
1bd70 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 en initialized u
1bd80 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e sing [sqlite3_in
1bd90 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f itialize()] prio
1bda0 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e r .** to invokin
1bdb0 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 g sqlite3_comple
1bdc0 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 te16() then sqli
1bdd0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
1bde0 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 is invoked.** a
1bdf0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 utomatically by
1be00 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 sqlite3_complete
1be10 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 16(). If that i
1be20 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 nitialization fa
1be30 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 ils,.** then the
1be40 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 return value fr
1be50 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c om sqlite3_compl
1be60 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 ete16() will be
1be70 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 non-zero.** rega
1be80 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 rdless of whethe
1be90 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 r or not the inp
1bea0 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 ut SQL is comple
1beb0 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 te.)^.**.** The
1bec0 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 input to [sqlite
1bed0 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 3_complete()] mu
1bee0 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 st be a zero-ter
1bef0 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 minated.** UTF-8
1bf00 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 string..**.** T
1bf10 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c he input to [sql
1bf20 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 ite3_complete16(
1bf30 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 )] must be a zer
1bf40 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 o-terminated.**
1bf50 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e UTF-16 string in
1bf60 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 native byte ord
1bf70 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 er..*/.SQLITE_AP
1bf80 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
1bf90 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6d CALL sqlite3_com
1bfa0 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 plete(const char
1bfb0 20 2a 73 71 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 *sql);.SQLITE_A
1bfc0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 PI int SQLITE_ST
1bfd0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f DCALL sqlite3_co
1bfe0 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 mplete16(const v
1bff0 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a oid *sql);../*.*
1c000 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 * CAPI3REF: Regi
1c010 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 ster A Callback
1c020 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 To Handle SQLITE
1c030 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20 _BUSY Errors.**
1c040 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d KEYWORDS: {busy-
1c050 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b handler callback
1c060 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65 72 7d } {busy handler}
1c070 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
1c080 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 te3.**.** ^The s
1c090 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 qlite3_busy_hand
1c0a0 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75 74 69 ler(D,X,P) routi
1c0b0 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 ne sets a callba
1c0c0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a ck function X.**
1c0d0 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 that might be i
1c0e0 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 nvoked with argu
1c0f0 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a ment P whenever.
1c100 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 ** an attempt is
1c110 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 made to access
1c120 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 a database table
1c130 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
1c140 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
1c150 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e nnection] D when
1c160 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a another thread.
1c170 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 ** or process ha
1c180 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b s the table lock
1c190 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 ed..** The sqlit
1c1a0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 e3_busy_handler(
1c1b0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 ) interface is u
1c1c0 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 sed to implement
1c1d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 .** [sqlite3_bus
1c1e0 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64 y_timeout()] and
1c1f0 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 [PRAGMA busy_ti
1c200 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 meout]..**.** ^I
1c210 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 f the busy callb
1c220 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 ack is NULL, the
1c230 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a n [SQLITE_BUSY].
1c240 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 ** is returned i
1c250 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 mmediately upon
1c260 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 encountering the
1c270 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 lock. ^If the
1c280 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a busy callback.**
1c290 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 is not NULL, th
1c2a0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 en the callback
1c2b0 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 might be invoked
1c2c0 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 with two argume
1c2d0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 nts..**.** ^The
1c2e0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 first argument t
1c2f0 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c o the busy handl
1c300 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 er is a copy of
1c310 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 the void* pointe
1c320 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 r which.** is th
1c330 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 e third argument
1c340 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 to sqlite3_busy
1c350 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 _handler(). ^Th
1c360 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
1c370 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 t to.** the busy
1c380 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 handler callbac
1c390 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 k is the number
1c3a0 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 of times that th
1c3b0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 e busy handler h
1c3c0 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b as.** been invok
1c3d0 65 64 20 70 72 65 76 69 6f 75 73 6c 79 20 66 6f ed previously fo
1c3e0 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 r the same locki
1c3f0 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 ng event. ^If t
1c400 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 he.** busy callb
1c410 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 ack returns 0, t
1c420 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 hen no additiona
1c430 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d l attempts are m
1c440 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 ade to.** access
1c450 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e the database an
1c460 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 d [SQLITE_BUSY]
1c470 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74 is returned.** t
1c480 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f o the applicatio
1c490 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 n..** ^If the ca
1c4a0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e llback returns n
1c4b0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e on-zero, then an
1c4c0 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a other attempt.**
1c4d0 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 is made to acce
1c4e0 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ss the database
1c4f0 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 and the cycle re
1c500 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 peats..**.** The
1c510 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 presence of a b
1c520 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 usy handler does
1c530 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 not guarantee t
1c540 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 hat it will be i
1c550 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 nvoked.** when t
1c560 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e here is lock con
1c570 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c tention. ^If SQL
1c580 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 ite determines t
1c590 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 hat invoking the
1c5a0 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 busy.** handler
1c5b0 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e could result in
1c5c0 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 a deadlock, it
1c5d0 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e will go ahead an
1c5e0 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 d return [SQLITE
1c5f0 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 _BUSY].** to the
1c600 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 application ins
1c610 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 tead of invoking
1c620 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 20 68 61 the .** busy ha
1c630 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 ndler..** Consid
1c640 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 er a scenario wh
1c650 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 ere one process
1c660 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 is holding a rea
1c670 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 d lock that.** i
1c680 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 t is trying to p
1c690 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 romote to a rese
1c6a0 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a rved lock and.**
1c6b0 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 a second proces
1c6c0 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 s is holding a r
1c6d0 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 eserved lock tha
1c6e0 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a t it is trying.*
1c6f0 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 * to promote to
1c700 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 an exclusive loc
1c710 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72 k. The first pr
1c720 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f ocess cannot pro
1c730 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 ceed.** because
1c740 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 it is blocked by
1c750 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 the second and
1c760 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 the second proce
1c770 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f ss cannot.** pro
1c780 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20 ceed because it
1c790 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 is blocked by th
1c7a0 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 e first. If bot
1c7b0 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 h processes.** i
1c7c0 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 nvoke the busy h
1c7d0 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 andlers, neither
1c7e0 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 will make any p
1c7f0 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 rogress. Theref
1c800 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 ore,.** SQLite r
1c810 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 eturns [SQLITE_B
1c820 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 USY] for the fir
1c830 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 st process, hopi
1c840 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 ng that this.**
1c850 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 will induce the
1c860 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f first process to
1c870 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 release its rea
1c880 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 d lock and allow
1c890 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 .** the second p
1c8a0 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 rocess to procee
1c8b0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 d..**.** ^The de
1c8c0 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 fault busy callb
1c8d0 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a ack is NULL..**.
1c8e0 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f ** ^(There can o
1c8f0 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 nly be a single
1c900 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 busy handler def
1c910 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a ined for each.**
1c920 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
1c930 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 ction]. Setting
1c940 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 a new busy hand
1c950 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a ler clears any.*
1c960 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 * previously set
1c970 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f handler.)^ ^No
1c980 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 te that calling
1c990 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 [sqlite3_busy_ti
1c9a0 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 meout()].** or e
1c9b0 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 41 47 4d valuating [PRAGM
1c9c0 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e A busy_timeout=N
1c9d0 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 20 74 68 ] will change th
1c9e0 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 e.** busy handle
1c9f0 72 20 61 6e 64 20 74 68 75 73 20 63 6c 65 61 72 r and thus clear
1ca00 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 any previously
1ca10 73 65 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72 set busy handler
1ca20 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 ..**.** The busy
1ca30 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 callback should
1ca40 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 not take any ac
1ca50 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 tions which modi
1ca60 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 fy the.** databa
1ca70 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 se connection th
1ca80 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 at invoked the b
1ca90 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e usy handler. In
1caa0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a other words,.**
1cab0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 the busy handle
1cac0 72 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 r is not reentra
1cad0 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 nt. Any such ac
1cae0 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 tions.** result
1caf0 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 in undefined beh
1cb00 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 avior..** .** A
1cb10 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 busy handler mus
1cb20 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 t not close the
1cb30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1cb40 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 ion.** or [prepa
1cb50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 red statement] t
1cb60 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 hat invoked the
1cb70 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f busy handler..*/
1cb80 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
1cb90 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
1cba0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 qlite3_busy_hand
1cbb0 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e ler(sqlite3*, in
1cbc0 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c t(*)(void*,int),
1cbd0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 void*);../*.**
1cbe0 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 CAPI3REF: Set A
1cbf0 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 Busy Timeout.**
1cc00 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a METHOD: sqlite3.
1cc10 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 **.** ^This rout
1cc20 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 ine sets a [sqli
1cc30 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 te3_busy_handler
1cc40 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d | busy handler]
1cc50 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 that sleeps.**
1cc60 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20 for a specified
1cc70 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 amount of time w
1cc80 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c hen a table is l
1cc90 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e ocked. ^The han
1cca0 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 dler.** will sle
1ccb0 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 ep multiple time
1ccc0 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 s until at least
1ccd0 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e "ms" millisecon
1cce0 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a ds of sleeping.*
1ccf0 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 * have accumulat
1cd00 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c ed. ^After at l
1cd10 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 east "ms" millis
1cd20 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 econds of sleepi
1cd30 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c ng,.** the handl
1cd40 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 er returns 0 whi
1cd50 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 ch causes [sqlit
1cd60 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 e3_step()] to re
1cd70 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f turn.** [SQLITE_
1cd80 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 BUSY]..**.** ^Ca
1cd90 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 lling this routi
1cda0 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d ne with an argum
1cdb0 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 ent less than or
1cdc0 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a equal to zero.*
1cdd0 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 * turns off all
1cde0 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a busy handlers..*
1cdf0 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e *.** ^(There can
1ce00 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c only be a singl
1ce10 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 e busy handler f
1ce20 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a or a particular.
1ce30 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
1ce40 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20 nection] at any
1ce50 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 given moment. I
1ce60 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 f another busy h
1ce70 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 andler.** was de
1ce80 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 fined (using [s
1ce90 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 qlite3_busy_hand
1cea0 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f ler()]) prior to
1ceb0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 calling.** this
1cec0 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f routine, that o
1ced0 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 ther busy handle
1cee0 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a r is cleared.)^.
1cef0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
1cf00 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 [PRAGMA busy_ti
1cf10 6d 65 6f 75 74 5d 0a 2a 2f 0a 53 51 4c 49 54 45 meout].*/.SQLITE
1cf20 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f _API int SQLITE_
1cf30 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
1cf40 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c busy_timeout(sql
1cf50 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a ite3*, int ms);.
1cf60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1cf70 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 Convenience Rou
1cf80 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e tines For Runnin
1cf90 67 20 51 75 65 72 69 65 73 0a 2a 2a 20 4d 45 54 g Queries.** MET
1cfa0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a HOD: sqlite3.**.
1cfb0 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 ** This is a leg
1cfc0 61 63 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 acy interface th
1cfd0 61 74 20 69 73 20 70 72 65 73 65 72 76 65 64 20 at is preserved
1cfe0 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f for backwards co
1cff0 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 mpatibility..**
1d000 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 Use of this inte
1d010 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 rface is not rec
1d020 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 ommended..**.**
1d030 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 Definition: A <b
1d040 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 >result table</b
1d050 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 > is memory data
1d060 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74 structure creat
1d070 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 ed by the.** [sq
1d080 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 lite3_get_table(
1d090 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 )] interface. A
1d0a0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 result table re
1d0b0 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d cords the.** com
1d0c0 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75 plete query resu
1d0d0 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 lts from one or
1d0e0 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a more queries..**
1d0f0 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f .** The table co
1d100 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 nceptually has a
1d110 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 number of rows
1d120 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 and columns. Bu
1d130 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 t.** these numbe
1d140 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 rs are not part
1d150 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 of the result ta
1d160 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 ble itself. The
1d170 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 se.** numbers ar
1d180 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 e obtained separ
1d190 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 ately. Let N be
1d1a0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 the number of r
1d1b0 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 ows.** and M be
1d1c0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f the number of co
1d1d0 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 lumns..**.** A r
1d1e0 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 esult table is a
1d1f0 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 n array of point
1d200 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d ers to zero-term
1d210 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 inated UTF-8 str
1d220 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 ings..** There a
1d230 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 re (N+1)*M eleme
1d240 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 nts in the array
1d250 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 . The first M p
1d260 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a ointers point.**
1d270 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 to zero-termina
1d280 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 ted strings that
1d290 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 contain the na
1d2a0 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d mes of the colum
1d2b0 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 ns..** The remai
1d2c0 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c ning entries all
1d2d0 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 point to query
1d2e0 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 results. NULL v
1d2f0 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 alues result.**
1d300 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 in NULL pointers
1d310 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c . All other val
1d320 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 ues are in their
1d330 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d UTF-8 zero-term
1d340 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 inated.** string
1d350 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 representation
1d360 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b as returned by [
1d370 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
1d380 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 ext()]..**.** A
1d390 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 result table mig
1d3a0 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e ht consist of on
1d3b0 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 e or more memory
1d3c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a allocations..**
1d3d0 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 It is not safe
1d3e0 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 to pass a result
1d3f0 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 table directly
1d400 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 to [sqlite3_free
1d410 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 ()]..** A result
1d420 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 table should be
1d430 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 deallocated usi
1d440 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ng [sqlite3_free
1d450 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a _table()]..**.**
1d460 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 ^(As an example
1d470 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 of the result t
1d480 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 able format, sup
1d490 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73 pose a query res
1d4a0 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c ult.** is as fol
1d4b0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f lows:.**.** <blo
1d4c0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a ckquote><pre>.**
1d4d0 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 Name
1d4e0 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 | Age.**
1d4f0 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ------------
1d500 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 -----------.**
1d510 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 Alice
1d520 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 | 43.**
1d530 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 Bob | 2
1d540 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 8.** Cind
1d550 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 y | 21.**
1d560 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
1d570 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 te>.**.** There
1d580 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 are two column (
1d590 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 M==2) and three
1d5a0 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 rows (N==3). Th
1d5b0 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 us the.** result
1d5c0 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 table has 8 ent
1d5d0 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 ries. Suppose t
1d5e0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 he result table
1d5f0 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 is stored.** in
1d600 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 an array names a
1d610 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 zResult. Then a
1d620 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 zResult holds th
1d630 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a is content:.**.*
1d640 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 * <blockquote><p
1d650 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a re>.** az
1d660 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 Result[0] =
1d670 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 "Name";.**
1d680 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 azResult[1
1d690 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 ] = "Age";.**
1d6a0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
1d6b0 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 1;2] = "Alice";.
1d6c0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
1d6d0 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 lt[3] = "43"
1d6e0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 ;.** azRe
1d6f0 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 sult[4] = "B
1d700 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 ob";.** a
1d710 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d zResult[5] =
1d720 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 "28";.**
1d730 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d azResult[6]
1d740 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 = "Cindy";.**
1d750 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 azResult&#
1d760 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 91;7] = "21";.**
1d770 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 </pre></blockqu
1d780 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ote>)^.**.** ^Th
1d790 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 e sqlite3_get_ta
1d7a0 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 ble() function e
1d7b0 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 valuates one or
1d7c0 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f more.** semicolo
1d7d0 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 n-separated SQL
1d7e0 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 statements in th
1d7f0 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 e zero-terminate
1d800 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e d UTF-8.** strin
1d810 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 g of its 2nd par
1d820 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 ameter and retur
1d830 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c ns a result tabl
1d840 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e e to the.** poin
1d850 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 ter given in its
1d860 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 3rd parameter..
1d870 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 **.** After the
1d880 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 application has
1d890 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 finished with th
1d8a0 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 e result from sq
1d8b0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 lite3_get_table(
1d8c0 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 ),.** it must pa
1d8d0 73 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 ss the result ta
1d8e0 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 ble pointer to s
1d8f0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c qlite3_free_tabl
1d900 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a e() in order to.
1d910 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d ** release the m
1d920 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d emory that was m
1d930 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 alloced. Becaus
1d940 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 e of the way the
1d950 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c .** [sqlite3_mal
1d960 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 loc()] happens w
1d970 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 ithin sqlite3_ge
1d980 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 t_table(), the c
1d990 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 alling.** functi
1d9a0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 on must not try
1d9b0 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 to call [sqlite3
1d9c0 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c _free()] directl
1d9d0 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c y. Only.** [sql
1d9e0 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 ite3_free_table(
1d9f0 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 )] is able to re
1da00 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 lease the memory
1da10 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 properly and sa
1da20 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 fely..**.** The
1da30 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c sqlite3_get_tabl
1da40 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 e() interface is
1da50 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 implemented as
1da60 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 a wrapper around
1da70 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 .** [sqlite3_exe
1da80 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 c()]. The sqlit
1da90 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 e3_get_table() r
1daa0 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 outine does not
1dab0 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 have access.** t
1dac0 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 o any internal d
1dad0 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f ata structures o
1dae0 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 f SQLite. It us
1daf0 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c es only the publ
1db00 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 ic.** interface
1db10 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 defined here. A
1db20 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c s a consequence,
1db30 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 errors that occ
1db40 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 ur in the.** wra
1db50 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 pper layer outsi
1db60 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e de of the intern
1db70 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 al [sqlite3_exec
1db80 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 ()] call are not
1db90 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e .** reflected in
1dba0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c subsequent call
1dbb0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 s to [sqlite3_er
1dbc0 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b rcode()] or.** [
1dbd0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 sqlite3_errmsg()
1dbe0 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 ]..*/.SQLITE_API
1dbf0 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
1dc00 41 4c 4c 20 73 71 6c 69 74 65 33 5f 67 65 74 5f ALL sqlite3_get_
1dc10 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 table(. sqlite3
1dc20 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f *db, /
1dc30 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 * An open databa
1dc40 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 se */. const ch
1dc50 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a ar *zSql, /*
1dc60 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 SQL to be evalu
1dc70 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a ated */. char *
1dc80 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 **pazResult,
1dc90 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 /* Results of th
1dca0 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 e query */. int
1dcb0 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 *pnRow,
1dcc0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 /* Number of
1dcd0 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 result rows writ
1dce0 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e ten here */. in
1dcf0 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 t *pnColumn,
1dd00 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 /* Number of
1dd10 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 result columns
1dd20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a written here */.
1dd30 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 char **pzErrms
1dd40 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 g /* Error
1dd50 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 msg written her
1dd60 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 e */.);.SQLITE_A
1dd70 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 PI void SQLITE_S
1dd80 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 66 TDCALL sqlite3_f
1dd90 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a ree_table(char *
1dda0 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a *result);../*.**
1ddb0 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 CAPI3REF: Forma
1ddc0 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e tted String Prin
1ddd0 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a ting Functions.*
1dde0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
1ddf0 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 nes are work-ali
1de00 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e kes of the "prin
1de10 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 tf()" family of
1de20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f functions.** fro
1de30 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 m the standard C
1de40 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 library..** The
1de50 73 65 20 72 6f 75 74 69 6e 65 73 20 75 6e 64 65 se routines unde
1de60 72 73 74 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74 rstand most of t
1de70 68 65 20 63 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f he common K&R fo
1de80 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 rmatting options
1de90 2c 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d 65 20 61 ,.** plus some a
1dea0 64 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 dditional non-st
1deb0 61 6e 64 61 72 64 20 66 6f 72 6d 61 74 73 2c 20 andard formats,
1dec0 64 65 74 61 69 6c 65 64 20 62 65 6c 6f 77 2e 0a detailed below..
1ded0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 73 6f 6d ** Note that som
1dee0 65 20 6f 66 20 74 68 65 20 6d 6f 72 65 20 6f 62 e of the more ob
1def0 73 63 75 72 65 20 66 6f 72 6d 61 74 74 69 6e 67 scure formatting
1df00 20 6f 70 74 69 6f 6e 73 20 66 72 6f 6d 20 72 65 options from re
1df10 63 65 6e 74 0a 2a 2a 20 43 2d 6c 69 62 72 61 72 cent.** C-librar
1df20 79 20 73 74 61 6e 64 61 72 64 73 20 61 72 65 20 y standards are
1df30 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 69 omitted from thi
1df40 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e s implementation
1df50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
1df60 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 ite3_mprintf() a
1df70 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 nd sqlite3_vmpri
1df80 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 ntf() routines w
1df90 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 rite their.** re
1dfa0 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 sults into memor
1dfb0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 y obtained from
1dfc0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
1dfd0 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e )]..** The strin
1dfe0 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 gs returned by t
1dff0 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 hese two routine
1e000 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 s should be.** r
1e010 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 eleased by [sqli
1e020 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 te3_free()]. ^B
1e030 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 oth routines ret
1e040 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f urn a.** NULL po
1e050 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 inter if [sqlite
1e060 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 3_malloc()] is u
1e070 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 nable to allocat
1e080 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f e enough.** memo
1e090 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 ry to hold the r
1e0a0 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e esulting string.
1e0b0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c .**.** ^(The sql
1e0c0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 ite3_snprintf()
1e0d0 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c routine is simil
1e0e0 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 ar to "snprintf(
1e0f0 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 )" from.** the s
1e100 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 tandard C librar
1e110 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 y. The result i
1e120 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 s written into t
1e130 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 he.** buffer sup
1e140 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63 plied as the sec
1e150 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 ond parameter wh
1e160 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 ose size is give
1e170 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 n by.** the firs
1e180 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 t parameter. Not
1e190 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 e that the order
1e1a0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 of the.** first
1e1b0 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 two parameters
1e1c0 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d is reversed from
1e1d0 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 snprintf().)^
1e1e0 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 This is an.** hi
1e1f0 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e storical acciden
1e200 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 t that cannot be
1e210 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 fixed without b
1e220 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 reaking.** backw
1e230 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 ards compatibili
1e240 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f ty. ^(Note also
1e250 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e that sqlite3_sn
1e260 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 printf().** retu
1e270 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
1e280 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 its buffer inst
1e290 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 ead of the numbe
1e2a0 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 r of.** characte
1e2b0 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 rs actually writ
1e2c0 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 ten into the buf
1e2d0 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 fer.)^ We admit
1e2e0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d that.** the num
1e2f0 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 ber of character
1e300 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 s written would
1e310 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c be a more useful
1e320 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 return.** value
1e330 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 but we cannot c
1e340 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d hange the implem
1e350 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 entation of sqli
1e360 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a te3_snprintf().*
1e370 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 * now without br
1e380 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 eaking compatibi
1e390 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 lity..**.** ^As
1e3a0 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 long as the buff
1e3b0 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 er size is great
1e3c0 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 er than zero, sq
1e3d0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 lite3_snprintf()
1e3e0 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 .** guarantees t
1e3f0 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69 hat the buffer i
1e400 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 s always zero-te
1e410 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 rminated. ^The
1e420 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 first.** paramet
1e430 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f er "n" is the to
1e440 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 tal size of the
1e450 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e buffer, includin
1e460 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 g space for.** t
1e470 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 he zero terminat
1e480 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 or. So the long
1e490 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 est string that
1e4a0 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c can be completel
1e4b0 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c y.** written wil
1e4c0 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 l be n-1 charact
1e4d0 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ers..**.** ^The
1e4e0 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 sqlite3_vsnprint
1e4f0 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 f() routine is a
1e500 20 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e varargs version
1e510 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 of sqlite3_snpr
1e520 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 intf()..**.** Th
1e530 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c ese routines all
1e540 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 implement some
1e550 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 additional forma
1e560 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 tting.** options
1e570 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c that are useful
1e580 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e for constructin
1e590 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 g SQL statements
1e5a0 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 ..** All of the
1e5b0 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 usual printf() f
1e5c0 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e ormatting option
1e5d0 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 s apply. In add
1e5e0 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 ition, there.**
1e5f0 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 is are "%q", "%Q
1e600 22 2c 20 22 25 77 22 20 61 6e 64 20 22 25 7a 22 ", "%w" and "%z"
1e610 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 options..**.**
1e620 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 ^(The %q option
1e630 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e works like %s in
1e640 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74 that it substit
1e650 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 utes a nul-termi
1e660 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 nated.** string
1e670 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e from the argumen
1e680 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 t list. But %q
1e690 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 also doubles eve
1e6a0 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 ry '\'' characte
1e6b0 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 r..** %q is desi
1e6c0 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 gned for use ins
1e6d0 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 ide a string lit
1e6e0 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 eral.)^ By doub
1e6f0 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a ling each '\''.*
1e700 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65 * character it e
1e710 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72 scapes that char
1e720 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 acter and allows
1e730 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 it to be insert
1e740 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 ed into.** the s
1e750 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 tring..**.** For
1e760 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 example, assume
1e770 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 the string vari
1e780 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 able zText conta
1e790 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c ins text as foll
1e7a0 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 ows:.**.** <bloc
1e7b0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 kquote><pre>.**
1e7c0 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 char *zText = "
1e7d0 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 It's a happy day
1e7e0 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 !";.** </pre></b
1e7f0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a lockquote>.**.**
1e800 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 One can use thi
1e810 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c s text in an SQL
1e820 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f statement as fo
1e830 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c llows:.**.** <bl
1e840 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
1e850 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 * char *zSQL =
1e860 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 sqlite3_mprintf(
1e870 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 "INSERT INTO tab
1e880 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 le VALUES('%q')"
1e890 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 , zText);.** sq
1e8a0 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a lite3_exec(db, z
1e8b0 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a SQL, 0, 0, 0);.*
1e8c0 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 * sqlite3_free(
1e8d0 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e zSQL);.** </pre>
1e8e0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a </blockquote>.**
1e8f0 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 .** Because the
1e900 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 %q format string
1e910 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c is used, the '\
1e920 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 '' character in
1e930 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 zText.** is esca
1e940 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 ped and the SQL
1e950 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 generated is as
1e960 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c follows:.**.** <
1e970 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
1e980 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f .** INSERT INTO
1e990 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 table1 VALUES('
1e9a0 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61 It''s a happy da
1e9b0 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f y!').** </pre></
1e9c0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a blockquote>.**.*
1e9d0 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 * This is correc
1e9e0 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20 t. Had we used
1e9f0 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 %s instead of %q
1ea00 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 , the generated
1ea10 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 SQL.** would hav
1ea20 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 e looked like th
1ea30 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b is:.**.** <block
1ea40 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 quote><pre>.**
1ea50 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c INSERT INTO tabl
1ea60 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 e1 VALUES('It's
1ea70 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a a happy day!');.
1ea80 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
1ea90 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 quote>.**.** Thi
1eaa0 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 s second example
1eab0 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 is an SQL synta
1eac0 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 x error. As a g
1ead0 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 eneral rule you
1eae0 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 should.** always
1eaf0 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 use %q instead
1eb00 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 of %s when inser
1eb10 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 ting text into a
1eb20 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e string literal.
1eb30 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 .**.** ^(The %Q
1eb40 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b option works lik
1eb50 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 e %q except it a
1eb60 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 lso adds single
1eb70 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a quotes around.**
1eb80 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 the outside of
1eb90 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 the total string
1eba0 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c . Additionally,
1ebb0 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 if the paramete
1ebc0 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 r in the.** argu
1ebd0 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e ment list is a N
1ebe0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 ULL pointer, %Q
1ebf0 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 substitutes the
1ec00 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 text "NULL" (wit
1ec10 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 hout.** single q
1ec20 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 uotes).)^ So, f
1ec30 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 or example, one
1ec40 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a could say:.**.**
1ec50 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 <blockquote><pr
1ec60 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 e>.** char *zSQ
1ec70 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 L = sqlite3_mpri
1ec80 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f ntf("INSERT INTO
1ec90 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 table VALUES(%Q
1eca0 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 )", zText);.**
1ecb0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c sqlite3_exec(db,
1ecc0 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b zSQL, 0, 0, 0);
1ecd0 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 .** sqlite3_fre
1ece0 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 e(zSQL);.** </pr
1ecf0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a e></blockquote>.
1ed00 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 **.** The code a
1ed10 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 bove will render
1ed20 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 a correct SQL s
1ed30 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 tatement in the
1ed40 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 zSQL.** variable
1ed50 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 even if the zTe
1ed60 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 xt variable is a
1ed70 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a NULL pointer..*
1ed80 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 77 22 20 *.** ^(The "%w"
1ed90 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f formatting optio
1eda0 6e 20 69 73 20 6c 69 6b 65 20 22 25 71 22 20 65 n is like "%q" e
1edb0 78 63 65 70 74 20 74 68 61 74 20 69 74 20 65 78 xcept that it ex
1edc0 70 65 63 74 73 20 74 6f 0a 2a 2a 20 62 65 20 63 pects to.** be c
1edd0 6f 6e 74 61 69 6e 65 64 20 77 69 74 68 69 6e 20 ontained within
1ede0 64 6f 75 62 6c 65 2d 71 75 6f 74 65 73 20 69 6e double-quotes in
1edf0 73 74 65 61 64 20 6f 66 20 73 69 6e 67 6c 65 20 stead of single
1ee00 71 75 6f 74 65 73 2c 20 61 6e 64 20 69 74 0a 2a quotes, and it.*
1ee10 2a 20 65 73 63 61 70 65 73 20 74 68 65 20 64 6f * escapes the do
1ee20 75 62 6c 65 2d 71 75 6f 74 65 20 63 68 61 72 61 uble-quote chara
1ee30 63 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 cter instead of
1ee40 74 68 65 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65 the single-quote
1ee50 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 2e 29 5e .** character.)^
1ee60 20 20 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61 The "%w" forma
1ee70 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 tting option is
1ee80 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 73 61 66 intended for saf
1ee90 65 6c 79 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a ely inserting.**
1eea0 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d table and colum
1eeb0 6e 20 6e 61 6d 65 73 20 69 6e 74 6f 20 61 20 63 n names into a c
1eec0 6f 6e 73 74 72 75 63 74 65 64 20 53 51 4c 20 73 onstructed SQL s
1eed0 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 tatement..**.**
1eee0 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 ^(The "%z" forma
1eef0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 tting option wor
1ef00 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 ks like "%s" but
1ef10 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 with the.** add
1ef20 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 ition that after
1ef30 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 the string has
1ef40 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f been read and co
1ef50 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 pied into.** the
1ef60 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 result, [sqlite
1ef70 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 3_free()] is cal
1ef80 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 led on the input
1ef90 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 string.)^.*/.SQ
1efa0 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 53 LITE_API char *S
1efb0 51 4c 49 54 45 5f 43 44 45 43 4c 20 73 71 6c 69 QLITE_CDECL sqli
1efc0 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 te3_mprintf(cons
1efd0 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 t char*,...);.SQ
1efe0 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 53 LITE_API char *S
1eff0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
1f000 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 lite3_vmprintf(c
1f010 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c onst char*, va_l
1f020 69 73 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ist);.SQLITE_API
1f030 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 43 44 char *SQLITE_CD
1f040 45 43 4c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 ECL sqlite3_snpr
1f050 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 intf(int,char*,c
1f060 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 onst char*, ...)
1f070 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 ;.SQLITE_API cha
1f080 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c r *SQLITE_STDCAL
1f090 4c 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 L sqlite3_vsnpri
1f0a0 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f ntf(int,char*,co
1f0b0 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 nst char*, va_li
1f0c0 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 st);../*.** CAPI
1f0d0 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 3REF: Memory All
1f0e0 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 ocation Subsyste
1f0f0 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 m.**.** The SQLi
1f100 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 te core uses the
1f110 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 se three routine
1f120 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 s for all of its
1f130 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c own.** internal
1f140 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
1f150 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 on needs. "Core"
1f160 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 in the previous
1f170 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 sentence.** doe
1f180 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 s not include op
1f190 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 erating-system s
1f1a0 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c pecific VFS impl
1f1b0 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 ementation. The
1f1c0 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 .** Windows VFS
1f1d0 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c uses native mall
1f1e0 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 oc() and free()
1f1f0 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 for some operati
1f200 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ons..**.** ^The
1f210 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
1f220 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
1f230 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
1f240 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f block.** of memo
1f250 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 ry at least N by
1f260 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 tes in length, w
1f270 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 here N is the pa
1f280 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 rameter..** ^If
1f290 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
1f2a0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 is unable to ob
1f2b0 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 tain sufficient
1f2c0 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 free.** memory,
1f2d0 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c it returns a NUL
1f2e0 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 L pointer. ^If
1f2f0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 the parameter N
1f300 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 to.** sqlite3_ma
1f310 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f lloc() is zero o
1f320 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 r negative then
1f330 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
1f340 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 returns.** a NU
1f350 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a LL pointer..**.*
1f360 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d * ^The sqlite3_m
1f370 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75 74 69 alloc64(N) routi
1f380 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74 20 6c 69 ne works just li
1f390 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 ke.** sqlite3_ma
1f3a0 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70 74 20 74 lloc(N) except t
1f3b0 68 61 74 20 4e 20 69 73 20 61 6e 20 75 6e 73 69 hat N is an unsi
1f3c0 67 6e 65 64 20 36 34 2d 62 69 74 20 69 6e 74 65 gned 64-bit inte
1f3d0 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f ger instead.** o
1f3e0 66 20 61 20 73 69 67 6e 65 64 20 33 32 2d 62 69 f a signed 32-bi
1f3f0 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a t integer..**.**
1f400 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 ^Calling sqlite
1f410 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20 3_free() with a
1f420 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 pointer previous
1f430 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 ly returned.** b
1f440 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 y sqlite3_malloc
1f450 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 () or sqlite3_re
1f460 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 alloc() releases
1f470 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a that memory so.
1f480 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 ** that it might
1f490 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68 be reused. ^Th
1f4a0 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 e sqlite3_free()
1f4b0 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 routine is.** a
1f4c0 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c no-op if is cal
1f4d0 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 led with a NULL
1f4e0 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e pointer. Passin
1f4f0 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 g a NULL pointer
1f500 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 .** to sqlite3_f
1f510 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 ree() is harmles
1f520 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 s. After being
1f530 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a freed, memory.**
1f540 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 should neither
1f550 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 be read nor writ
1f560 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 ten. Even readi
1f570 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 ng previously fr
1f580 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 eed.** memory mi
1f590 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 ght result in a
1f5a0 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 segmentation fau
1f5b0 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 lt or other seve
1f5c0 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d re error..** Mem
1f5d0 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 ory corruption,
1f5e0 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 a segmentation f
1f5f0 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 ault, or other s
1f600 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d evere error.** m
1f610 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 ight result if s
1f620 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 qlite3_free() is
1f630 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e called with a n
1f640 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 on-NULL pointer
1f650 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 that.** was not
1f660 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 obtained from sq
1f670 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f lite3_malloc() o
1f680 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f r sqlite3_reallo
1f690 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 c()..**.** ^The
1f6a0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
1f6b0 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 61 X,N) interface a
1f6c0 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a ttempts to resiz
1f6d0 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d e a.** prior mem
1f6e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 58 ory allocation X
1f6f0 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 to be at least
1f700 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 N bytes..** ^If
1f710 74 68 65 20 58 20 70 61 72 61 6d 65 74 65 72 20 the X parameter
1f720 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c to sqlite3_reall
1f730 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20 61 20 oc(X,N).** is a
1f740 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 NULL pointer the
1f750 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 n its behavior i
1f760 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 s identical to c
1f770 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 alling.** sqlite
1f780 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 3_malloc(N)..**
1f790 5e 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d 65 ^If the N parame
1f7a0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 ter to sqlite3_r
1f7b0 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73 20 7a ealloc(X,N) is z
1f7c0 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 ero or.** negati
1f7d0 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 ve then the beha
1f7e0 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 vior is exactly
1f7f0 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c the same as call
1f800 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 ing.** sqlite3_f
1f810 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71 6c 69 ree(X)..** ^sqli
1f820 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 te3_realloc(X,N)
1f830 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
1f840 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 er to a memory a
1f850 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 llocation.** of
1f860 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 at least N bytes
1f870 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c in size or NULL
1f880 20 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e 74 if insufficient
1f890 20 6d 65 6d 6f 72 79 20 69 73 20 61 76 61 69 6c memory is avail
1f8a0 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 able..** ^If M i
1f8b0 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 s the size of th
1f8c0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 e prior allocati
1f8d0 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d on, then min(N,M
1f8e0 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 ) bytes.** of th
1f8f0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 e prior allocati
1f900 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e on are copied in
1f910 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 to the beginning
1f920 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72 of buffer retur
1f930 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 ned.** by sqlite
1f940 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 61 3_realloc(X,N) a
1f950 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c nd the prior all
1f960 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 ocation is freed
1f970 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 ..** ^If sqlite3
1f980 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 _realloc(X,N) re
1f990 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 20 4e turns NULL and N
1f9a0 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74 68 is positive, th
1f9b0 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f 72 20 en the.** prior
1f9c0 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 6e 6f allocation is no
1f9d0 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e t freed..**.** ^
1f9e0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c The sqlite3_real
1f9f0 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74 65 72 loc64(X,N) inter
1fa00 66 61 63 65 73 20 77 6f 72 6b 73 20 74 68 65 20 faces works the
1fa10 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69 74 same as.** sqlit
1fa20 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 e3_realloc(X,N)
1fa30 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69 73 except that N is
1fa40 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69 67 6e a 64-bit unsign
1fa50 65 64 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65 ed integer inste
1fa60 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d 62 69 ad.** of a 32-bi
1fa70 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 t signed integer
1fa80 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20 69 73 ..**.** ^If X is
1fa90 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 a memory alloca
1faa0 74 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 tion previously
1fab0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 obtained from sq
1fac0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 0a lite3_malloc(),.
1fad0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f ** sqlite3_mallo
1fae0 63 36 34 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 c64(), sqlite3_r
1faf0 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73 71 6c ealloc(), or sql
1fb00 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 ite3_realloc64()
1fb10 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 , then.** sqlite
1fb20 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72 3_msize(X) retur
1fb30 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 ns the size of t
1fb40 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 hat memory alloc
1fb50 61 74 69 6f 6e 20 69 6e 20 62 79 74 65 73 2e 0a ation in bytes..
1fb60 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 ** ^The value re
1fb70 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 turned by sqlite
1fb80 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67 68 74 3_msize(X) might
1fb90 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 be larger than
1fba0 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 the number.** of
1fbb0 20 62 79 74 65 73 20 72 65 71 75 65 73 74 65 64 bytes requested
1fbc0 20 77 68 65 6e 20 58 20 77 61 73 20 61 6c 6c 6f when X was allo
1fbd0 63 61 74 65 64 2e 20 20 5e 49 66 20 58 20 69 73 cated. ^If X is
1fbe0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
1fbf0 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f then.** sqlite3_
1fc00 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73 msize(X) returns
1fc10 20 7a 65 72 6f 2e 20 20 49 66 20 58 20 70 6f 69 zero. If X poi
1fc20 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68 69 6e 67 nts to something
1fc30 20 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a 2a 20 that is not.**
1fc40 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 the beginning of
1fc50 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
1fc60 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20 70 6f 69 on, or if it poi
1fc70 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d 65 72 6c nts to a formerl
1fc80 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d 6f 72 y.** valid memor
1fc90 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 68 61 y allocation tha
1fca0 74 20 68 61 73 20 6e 6f 77 20 62 65 65 6e 20 66 t has now been f
1fcb0 72 65 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62 reed, then the b
1fcc0 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 73 71 ehavior.** of sq
1fcd0 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 69 lite3_msize(X) i
1fce0 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 s undefined and
1fcf0 70 6f 73 73 69 62 6c 79 20 68 61 72 6d 66 75 6c possibly harmful
1fd00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d ..**.** ^The mem
1fd10 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 ory returned by
1fd20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
1fd30 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f , sqlite3_reallo
1fd40 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f c(),.** sqlite3_
1fd50 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e 64 20 malloc64(), and
1fd60 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 sqlite3_realloc6
1fd70 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 4().** is always
1fd80 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c aligned to at l
1fd90 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 east an 8 byte b
1fda0 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61 oundary, or to a
1fdb0 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64 .** 4 byte bound
1fdc0 61 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49 ary if the [SQLI
1fdd0 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45 TE_4_BYTE_ALIGNE
1fde0 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c D_MALLOC] compil
1fdf0 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e e-time.** option
1fe00 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 is used..**.**
1fe10 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f In SQLite versio
1fe20 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e n 3.5.0 and 3.5.
1fe30 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 1, it was possib
1fe40 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 le to define.**
1fe50 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f the SQLITE_OMIT_
1fe60 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f MEMORY_ALLOCATIO
1fe70 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 N which would ca
1fe80 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e use the built-in
1fe90 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
1fea0 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 on of these rout
1feb0 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 ines to be omitt
1fec0 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 ed. That capabi
1fed0 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f lity.** is no lo
1fee0 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 nger provided.
1fef0 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 Only built-in me
1ff00 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 mory allocators
1ff10 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a can be used..**.
1ff20 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 ** Prior to SQLi
1ff30 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31 te version 3.7.1
1ff40 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20 4f 0, the Windows O
1ff50 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 S interface laye
1ff60 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 r called.** the
1ff70 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 system malloc()
1ff80 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63 and free() direc
1ff90 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 tly when convert
1ffa0 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 ing.** filenames
1ffb0 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 between the UTF
1ffc0 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 -8 encoding used
1ffd0 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e by SQLite.** an
1ffe0 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e d whatever filen
1fff0 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 ame encoding is
20000 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74 used by the part
20010 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a icular Windows.*
20020 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 * installation.
20030 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 Memory allocati
20040 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20 64 on errors were d
20050 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 etected, but.**
20060 74 68 65 79 20 77 65 72 65 20 72 65 70 6f 72 74 they were report
20070 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 ed back as [SQLI
20080 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a TE_CANTOPEN] or.
20090 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 ** [SQLITE_IOERR
200a0 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 ] rather than [S
200b0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a QLITE_NOMEM]..**
200c0 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 .** The pointer
200d0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 arguments to [sq
200e0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e lite3_free()] an
200f0 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c d [sqlite3_reall
20100 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 oc()].** must be
20110 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 either NULL or
20120 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 else pointers ob
20130 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 tained from a pr
20140 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f ior.** invocatio
20150 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 n of [sqlite3_ma
20160 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 lloc()] or [sqli
20170 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 te3_realloc()] t
20180 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 hat have.** not
20190 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65 yet been release
201a0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 d..**.** The app
201b0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f lication must no
201c0 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 t read or write
201d0 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 any part of.** a
201e0 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 block of memory
201f0 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 after it has be
20200 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e en released usin
20210 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 g.** [sqlite3_fr
20220 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 ee()] or [sqlite
20230 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 3_realloc()]..*/
20240 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
20250 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c *SQLITE_STDCALL
20260 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
20270 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 int);.SQLITE_API
20280 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 void *SQLITE_ST
20290 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 61 DCALL sqlite3_ma
202a0 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65 33 5f 75 lloc64(sqlite3_u
202b0 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 int64);.SQLITE_A
202c0 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f PI void *SQLITE_
202d0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
202e0 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 realloc(void*, i
202f0 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 nt);.SQLITE_API
20300 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 void *SQLITE_STD
20310 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 61 CALL sqlite3_rea
20320 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73 71 lloc64(void*, sq
20330 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 53 lite3_uint64);.S
20340 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 QLITE_API void S
20350 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
20360 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a lite3_free(void*
20370 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 );.SQLITE_API sq
20380 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 53 51 4c lite3_uint64 SQL
20390 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
203a0 74 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 te3_msize(void*)
203b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
203c0 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 F: Memory Alloca
203d0 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a tor Statistics.*
203e0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 *.** SQLite prov
203f0 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 ides these two i
20400 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 nterfaces for re
20410 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 porting on the s
20420 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 tatus.** of the
20430 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
20440 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 )], [sqlite3_fre
20450 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 e()], and [sqlit
20460 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a e3_realloc()].**
20470 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 routines, which
20480 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d form the built-
20490 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 in memory alloca
204a0 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a tion subsystem..
204b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 **.** ^The [sqli
204c0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 te3_memory_used(
204d0 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 )] routine retur
204e0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
204f0 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d bytes.** of mem
20500 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 ory currently ou
20510 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f tstanding (mallo
20520 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 ced but not free
20530 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c d)..** ^The [sql
20540 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 ite3_memory_high
20550 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 water()] routine
20560 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 returns the max
20570 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 imum.** value of
20580 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 [sqlite3_memory
20590 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 _used()] since t
205a0 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 he high-water ma
205b0 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 rk.** was last r
205c0 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 eset. ^The valu
205d0 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b es returned by [
205e0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 sqlite3_memory_u
205f0 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 sed()] and.** [s
20600 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 qlite3_memory_hi
20610 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 ghwater()] inclu
20620 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a de any overhead.
20630 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 ** added by SQLi
20640 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d te in its implem
20650 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c entation of [sql
20660 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a ite3_malloc()],.
20670 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 ** but not overh
20680 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65 ead added by the
20690 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 any underlying
206a0 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a system library.*
206b0 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 * routines that
206c0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
206d0 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a )] may call..**.
206e0 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 ** ^The memory h
206f0 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 igh-water mark i
20700 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 s reset to the c
20710 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a urrent value of.
20720 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f ** [sqlite3_memo
20730 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e ry_used()] if an
20740 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 d only if the pa
20750 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 rameter to.** [s
20760 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 qlite3_memory_hi
20770 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 ghwater()] is tr
20780 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 ue. ^The value
20790 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b returned.** by [
207a0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 sqlite3_memory_h
207b0 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 ighwater(1)] is
207c0 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d the high-water m
207d0 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 ark.** prior to
207e0 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 53 51 the reset..*/.SQ
207f0 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 LITE_API sqlite3
20800 5f 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 54 _int64 SQLITE_ST
20810 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 65 DCALL sqlite3_me
20820 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b mory_used(void);
20830 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 .SQLITE_API sqli
20840 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 45 te3_int64 SQLITE
20850 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
20860 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 _memory_highwate
20870 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 r(int resetFlag)
20880 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
20890 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d F: Pseudo-Random
208a0 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f Number Generato
208b0 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 r.**.** SQLite c
208c0 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 ontains a high-q
208d0 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 uality pseudo-ra
208e0 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 ndom number gene
208f0 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 rator (PRNG) use
20900 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 d to.** select r
20910 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 andom [ROWID | R
20920 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 OWIDs] when inse
20930 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 rting new record
20940 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 s into a table t
20950 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 hat.** already u
20960 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 ses the largest
20970 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d possible [ROWID]
20980 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 . The PRNG is a
20990 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 lso used for.**
209a0 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e the build-in ran
209b0 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d dom() and random
209c0 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 blob() SQL funct
209d0 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 ions. This inte
209e0 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 rface allows.**
209f0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 applications to
20a00 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 access the same
20a10 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 PRNG for other p
20a20 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e urposes..**.** ^
20a30 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 A call to this r
20a40 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 outine stores N
20a50 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e bytes of randomn
20a60 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 ess into buffer
20a70 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 70 61 72 P..** ^The P par
20a80 61 6d 65 74 65 72 20 63 61 6e 20 62 65 20 61 20 ameter can be a
20a90 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a NULL pointer..**
20aa0 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 72 6f 75 .** ^If this rou
20ab0 74 69 6e 65 20 68 61 73 20 6e 6f 74 20 62 65 65 tine has not bee
20ac0 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 63 61 6c n previously cal
20ad0 6c 65 64 20 6f 72 20 69 66 20 74 68 65 20 70 72 led or if the pr
20ae0 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c 20 68 evious.** call h
20af0 61 64 20 4e 20 6c 65 73 73 20 74 68 61 6e 20 6f ad N less than o
20b00 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 ne or a NULL poi
20b10 6e 74 65 72 20 66 6f 72 20 50 2c 20 74 68 65 6e nter for P, then
20b20 20 74 68 65 20 50 52 4e 47 20 69 73 0a 2a 2a 20 the PRNG is.**
20b30 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e seeded using ran
20b40 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 domness obtained
20b50 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f from the xRando
20b60 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 0a mness method of.
20b70 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b ** the default [
20b80 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a sqlite3_vfs] obj
20b90 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ect..** ^If the
20ba0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f previous call to
20bb0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61 this routine ha
20bc0 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72 20 6d d an N of 1 or m
20bd0 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20 6e 6f 6e ore and a.** non
20be0 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20 74 68 65 -NULL P then the
20bf0 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 pseudo-randomne
20c00 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a ss is generated.
20c10 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e ** internally an
20c20 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 d without recour
20c30 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 se to the [sqlit
20c40 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e e3_vfs] xRandomn
20c50 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a ess.** method..*
20c60 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 /.SQLITE_API voi
20c70 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c d SQLITE_STDCALL
20c80 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e sqlite3_randomn
20c90 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 ess(int N, void
20ca0 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 *P);../*.** CAPI
20cb0 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 3REF: Compile-Ti
20cc0 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e me Authorization
20cd0 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 Callbacks.** ME
20ce0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a THOD: sqlite3.**
20cf0 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e .** ^This routin
20d00 65 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 e registers an a
20d10 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
20d20 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63 ck with a partic
20d30 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 ular.** [databas
20d40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 e connection], s
20d50 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 upplied in the f
20d60 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a irst argument..*
20d70 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 * ^The authorize
20d80 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e r callback is in
20d90 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 voked as SQL sta
20da0 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e tements are bein
20db0 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 g compiled.** by
20dc0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
20dd0 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 e()] or its vari
20de0 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 ants [sqlite3_pr
20df0 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 epare_v2()],.**
20e00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
20e10 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 16()] and [sqlit
20e20 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
20e30 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 )]. ^At various
20e40 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e .** points durin
20e50 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f g the compilatio
20e60 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f n process, as lo
20e70 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 gic is being cre
20e80 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f ated.** to perfo
20e90 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f rm various actio
20ea0 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a ns, the authoriz
20eb0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 er callback is i
20ec0 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 nvoked to.** see
20ed0 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e if those action
20ee0 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 s are allowed.
20ef0 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 ^The authorizer
20f00 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a callback should.
20f10 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 ** return [SQLIT
20f20 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 E_OK] to allow t
20f30 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 he action, [SQLI
20f40 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 TE_IGNORE] to di
20f50 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 sallow the.** sp
20f60 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 ecific action bu
20f70 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 t allow the SQL
20f80 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e statement to con
20f90 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 tinue to be.** c
20fa0 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c ompiled, or [SQL
20fb0 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 ITE_DENY] to cau
20fc0 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 se the entire SQ
20fd0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 L statement to b
20fe0 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 e.** rejected wi
20ff0 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 th an error. ^I
21000 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 f the authorizer
21010 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
21020 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f s.** any value o
21030 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 ther than [SQLIT
21040 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 E_IGNORE], [SQLI
21050 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 TE_OK], or [SQLI
21060 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e TE_DENY].** then
21070 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 the [sqlite3_pr
21080 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 epare_v2()] or e
21090 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 quivalent call t
210a0 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a hat triggered.**
210b0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
210c0 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 will fail with a
210d0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e n error message.
210e0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 .**.** When the
210f0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
21100 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 [SQLITE_OK], th
21110 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 at means the ope
21120 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 ration.** reques
21130 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 ted is ok. ^Whe
21140 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 n the callback r
21150 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 eturns [SQLITE_D
21160 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 ENY], the.** [sq
21170 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
21180 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e ()] or equivalen
21190 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 t call that trig
211a0 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 gered the.** aut
211b0 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 horizer will fai
211c0 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 l with an error
211d0 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 message explaini
211e0 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 ng that.** acces
211f0 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a s is denied. .**
21200 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 .** ^The first p
21210 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
21220 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
21230 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 ack is a copy of
21240 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 the third.** pa
21250 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 rameter to the s
21260 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
21270 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 rizer() interfac
21280 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 e. ^The second p
21290 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 arameter.** to t
212a0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 he callback is a
212b0 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 n integer [SQLIT
212c0 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 E_COPY | action
212d0 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 code] that speci
212e0 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 fies.** the part
212f0 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f icular action to
21300 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 be authorized.
21310 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 ^The third throu
21320 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 gh sixth paramet
21330 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 ers.** to the ca
21340 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d llback are zero-
21350 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e terminated strin
21360 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 gs that contain
21370 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 additional.** de
21380 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 tails about the
21390 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 action to be aut
213a0 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e horized..**.** ^
213b0 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f If the action co
213c0 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 de is [SQLITE_RE
213d0 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 AD].** and the c
213e0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 allback returns
213f0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 [SQLITE_IGNORE]
21400 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 then the.** [pre
21410 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
21420 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f statement is co
21430 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 nstructed to sub
21440 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c stitute.** a NUL
21450 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 L value in place
21460 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f of the table co
21470 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 lumn that would
21480 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 have.** been rea
21490 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d d if [SQLITE_OK]
214a0 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e had been return
214b0 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 ed. The [SQLITE
214c0 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 _IGNORE].** retu
214d0 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 rn can be used t
214e0 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 o deny an untrus
214f0 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20 ted user access
21500 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a to individual.**
21510 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 columns of a ta
21520 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ble..** ^If the
21530 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b action code is [
21540 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 SQLITE_DELETE] a
21550 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 nd the callback
21560 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 returns.** [SQLI
21570 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 TE_IGNORE] then
21580 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 the [DELETE] ope
21590 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 ration proceeds
215a0 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e but the.** [trun
215b0 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f cate optimizatio
215c0 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 n] is disabled a
215d0 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 nd all rows are
215e0 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 deleted individu
215f0 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 ally..**.** An a
21600 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 uthorizer is use
21610 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f d when [sqlite3_
21620 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 prepare | prepar
21630 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 ing].** SQL stat
21640 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 ements from an u
21650 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c ntrusted source,
21660 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 to ensure that
21670 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
21680 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 ts.** do not try
21690 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 to access data
216a0 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c they are not all
216b0 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 owed to see, or
216c0 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 that they do not
216d0 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 .** try to execu
216e0 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 te malicious sta
216f0 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d tements that dam
21700 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 age the database
21710 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c . For.** exampl
21720 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f e, an applicatio
21730 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 n may allow a us
21740 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 er to enter arbi
21750 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 trary.** SQL que
21760 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 ries for evaluat
21770 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 ion by a databas
21780 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c e. But the appl
21790 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 ication does.**
217a0 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 not want the use
217b0 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 r to be able to
217c0 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 make arbitrary c
217d0 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a hanges to the.**
217e0 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 database. An a
217f0 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 uthorizer could
21800 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 then be put in p
21810 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a lace while the.*
21820 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 * user-entered S
21830 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c QL is being [sql
21840 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 ite3_prepare | p
21850 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a repared] that.**
21860 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 disallows every
21870 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 thing except [SE
21880 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 LECT] statements
21890 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 ..**.** Applicat
218a0 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 ions that need t
218b0 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 o process SQL fr
218c0 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 om untrusted sou
218d0 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c rces.** might al
218e0 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 so consider lowe
218f0 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 ring resource li
21900 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 mits using [sqli
21910 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 te3_limit()].**
21920 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 and limiting dat
21930 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 abase size using
21940 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 the [max_page_c
21950 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a ount] [PRAGMA].*
21960 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f * in addition to
21970 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 using an author
21980 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e izer..**.** ^(On
21990 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 ly a single auth
219a0 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e orizer can be in
219b0 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 place on a data
219c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a base connection.
219d0 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 ** at a time. E
219e0 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 ach call to sqli
219f0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a te3_set_authoriz
21a00 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 er overrides the
21a10 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c .** previous cal
21a20 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 l.)^ ^Disable t
21a30 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 he authorizer by
21a40 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 installing a NU
21a50 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 LL callback..**
21a60 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 The authorizer i
21a70 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 s disabled by de
21a80 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 fault..**.** The
21a90 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
21aa0 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f back must not do
21ab0 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 anything that w
21ac0 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 ill modify.** th
21ad0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
21ae0 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b ction that invok
21af0 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 ed the authorize
21b00 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e r callback..** N
21b10 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 ote that [sqlite
21b20 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
21b30 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 and [sqlite3_ste
21b40 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 p()] both modify
21b50 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 their.** databa
21b60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 se connections f
21b70 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f or the meaning o
21b80 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 f "modify" in th
21b90 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a is paragraph..**
21ba0 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 .** ^When [sqlit
21bb0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
21bc0 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 is used to prep
21bd0 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c are a statement,
21be0 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e the.** statemen
21bf0 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 t might be re-pr
21c00 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 epared during [s
21c10 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 qlite3_step()] d
21c20 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 ue to a .** sche
21c30 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 ma change. Henc
21c40 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 e, the applicati
21c50 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 on should ensure
21c60 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 that the.** cor
21c70 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 rect authorizer
21c80 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 callback remains
21c90 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 in place during
21ca0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 the [sqlite3_st
21cb0 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f ep()]..**.** ^No
21cc0 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68 te that the auth
21cd0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
21ce0 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 is invoked only
21cf0 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 during.** [sqlit
21d00 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 e3_prepare()] or
21d10 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 its variants.
21d20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 Authorization is
21d30 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 not.** performe
21d40 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 d during stateme
21d50 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e nt evaluation in
21d60 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
21d70 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 ], unless.** as
21d80 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 stated in the pr
21d90 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 evious paragraph
21da0 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 , sqlite3_step()
21db0 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 invokes.** sqli
21dc0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
21dd0 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 to reprepare a
21de0 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 statement after
21df0 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e a schema change.
21e00 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
21e10 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c nt SQLITE_STDCAL
21e20 4c 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 L sqlite3_set_au
21e30 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 thorizer(. sqli
21e40 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 te3*,. int (*xA
21e50 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 uth)(void*,int,c
21e60 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 onst char*,const
21e70 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 char*,const cha
21e80 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c r*,const char*),
21e90 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 . void *pUserDa
21ea0 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ta.);../*.** CAP
21eb0 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 I3REF: Authorize
21ec0 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a r Return Codes.*
21ed0 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 *.** The [sqlite
21ee0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 3_set_authorizer
21ef0 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 | authorizer ca
21f00 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d llback function]
21f10 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 must.** return
21f20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f either [SQLITE_O
21f30 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 K] or one of the
21f40 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 se two constants
21f50 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 in order.** to
21f60 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 signal SQLite wh
21f70 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 ether or not the
21f80 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 action is permi
21f90 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a tted. See the.*
21fa0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 * [sqlite3_set_a
21fb0 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 uthorizer | auth
21fc0 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 orizer documenta
21fd0 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 tion] for additi
21fe0 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 onal.** informat
21ff0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 ion..**.** Note
22000 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f that SQLITE_IGNO
22010 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 RE is also used
22020 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72 as a [conflict r
22030 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a esolution mode].
22040 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d ** returned from
22050 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 the [sqlite3_vt
22060 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 ab_on_conflict()
22070 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a ] interface..*/.
22080 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
22090 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f ENY 1 /* Abo
220a0 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 rt the SQL state
220b0 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 ment with an err
220c0 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 or */.#define SQ
220d0 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 LITE_IGNORE 2
220e0 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 /* Don't allow a
220f0 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 ccess, but don't
22100 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 generate an err
22110 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 or */../*.** CAP
22120 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 I3REF: Authorize
22130 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a r Action Codes.*
22140 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 *.** The [sqlite
22150 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 3_set_authorizer
22160 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 ()] interface re
22170 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 gisters a callba
22180 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 ck function.** t
22190 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 hat is invoked t
221a0 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 o authorize cert
221b0 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ain SQL statemen
221c0 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a t actions. The.
221d0 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 ** second parame
221e0 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 ter to the callb
221f0 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 ack is an intege
22200 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 r code that spec
22210 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 ifies.** what ac
22220 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 tion is being au
22230 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 thorized. These
22240 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 are the integer
22250 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 action codes th
22260 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 at.** the author
22270 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 izer callback ma
22280 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a y be passed..**.
22290 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 ** These action
222a0 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e code values sign
222b0 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 ify what kind of
222c0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f operation is to
222d0 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 be.** authorize
222e0 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 d. The 3rd and
222f0 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 4th parameters t
22300 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 o the authorizat
22310 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 ion.** callback
22320 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 function will be
22330 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e parameters or N
22340 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e ULL depending on
22350 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a which of these.
22360 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 ** codes is used
22370 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 as the second p
22380 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 arameter. ^(The
22390 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 5th parameter t
223a0 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 o the.** authori
223b0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 zer callback is
223c0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
223d0 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 database ("main"
223e0 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 , "temp",.** etc
223f0 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 .) if applicable
22400 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 .)^ ^The 6th pa
22410 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 rameter to the a
22420 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
22430 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d ck.** is the nam
22440 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d e of the inner-m
22450 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 ost trigger or v
22460 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 iew that is resp
22470 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 onsible for.** t
22480 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 he access attemp
22490 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 t or NULL if thi
224a0 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 s access attempt
224b0 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f is directly fro
224c0 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 m.** top-level S
224d0 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a QL code..*/./***
224e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
224f0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
22500 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a ******** 3rd ***
22510 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a ********* 4th **
22520 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 *********/.#defi
22530 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
22540 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 _INDEX
22550 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 1 /* Index Nam
22560 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d e Table Nam
22570 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
22580 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
22590 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 TABLE 2
225a0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
225b0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
225c0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
225d0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 SQLITE_CREATE_T
225e0 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 EMP_INDEX 3
225f0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 /* Index Name
22600 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 Table Name
22610 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
22620 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 SQLITE_CREATE_TE
22630 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 MP_TABLE 4
22640 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
22650 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
22660 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
22670 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d QLITE_CREATE_TEM
22680 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20 P_TRIGGER 5
22690 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 /* Trigger Name
226a0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
226b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
226c0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 LITE_CREATE_TEMP
226d0 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f _VIEW 6 /
226e0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 * View Name
226f0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
22700 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
22710 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 ITE_CREATE_TRIGG
22720 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a ER 7 /*
22730 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 Trigger Name
22740 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
22750 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
22760 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 TE_CREATE_VIEW
22770 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 8 /*
22780 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 View Name
22790 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
227a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
227b0 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 E_DELETE
227c0 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 9 /* T
227d0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e able Name N
227e0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
227f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
22800 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 _DROP_INDEX
22810 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 10 /* In
22820 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 dex Name Ta
22830 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f ble Name */
22840 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
22850 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 DROP_TABLE
22860 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 11 /* Tab
22870 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c le Name NUL
22880 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
22890 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
228a0 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 ROP_TEMP_INDEX
228b0 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 12 /* Inde
228c0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c x Name Tabl
228d0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
228e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
228f0 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 OP_TEMP_TABLE
22900 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 13 /* Table
22910 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
22920 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
22930 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
22940 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 P_TEMP_TRIGGER
22950 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 14 /* Trigge
22960 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 r Name Table
22970 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
22980 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
22990 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 _TEMP_VIEW
229a0 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 15 /* View Na
229b0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 me NULL
229c0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
229d0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
229e0 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20 TRIGGER
229f0 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 16 /* Trigger
22a00 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 Name Table Na
22a10 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
22a20 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 ne SQLITE_DROP_V
22a30 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31 IEW 1
22a40 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 7 /* View Name
22a50 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 NULL
22a60 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
22a70 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 e SQLITE_INSERT
22a80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 18
22a90 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
22aa0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
22ab0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
22ac0 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 SQLITE_PRAGMA
22ad0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20 19
22ae0 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 /* Pragma Name
22af0 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 1st arg or
22b00 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 NULL */.#define
22b10 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 SQLITE_READ
22b20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20
22b30 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
22b40 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 Column Name
22b50 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
22b60 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 QLITE_SELECT
22b70 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20 21
22b80 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 /* NULL
22b90 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
22ba0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
22bb0 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e LITE_TRANSACTION
22bc0 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 22 /
22bd0 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 * Operation
22be0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
22bf0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
22c00 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 ITE_UPDATE
22c10 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 23 /*
22c20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
22c30 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 Column Name
22c40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
22c50 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 TE_ATTACH
22c60 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 24 /*
22c70 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 Filename
22c80 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
22c90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
22ca0 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20 E_DETACH
22cb0 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 25 /* D
22cc0 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e atabase Name N
22cd0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
22ce0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
22cf0 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 _ALTER_TABLE
22d00 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 26 /* Da
22d10 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 tabase Name Ta
22d20 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f ble Name */
22d30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
22d40 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 REINDEX
22d50 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 27 /* Ind
22d60 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c ex Name NUL
22d70 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
22d80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
22d90 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 NALYZE
22da0 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 28 /* Tabl
22db0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c e Name NULL
22dc0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
22dd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 define SQLITE_CR
22de0 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 EATE_VTABLE
22df0 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 29 /* Table
22e00 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c Name Modul
22e10 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 e Name */.#d
22e20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
22e30 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 P_VTABLE
22e40 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 30 /* Table
22e50 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 Name Module
22e60 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
22e70 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 fine SQLITE_FUNC
22e80 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 TION
22e90 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 31 /* NULL
22ea0 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f Functio
22eb0 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 n Name */.#def
22ec0 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 ine SQLITE_SAVEP
22ed0 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 OINT
22ee0 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 32 /* Operatio
22ef0 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e n Savepoin
22f00 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 t Name */.#defi
22f10 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 ne SQLITE_COPY
22f20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
22f30 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 0 /* No longer
22f40 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 used */.#define
22f50 20 53 51 4c 49 54 45 5f 52 45 43 55 52 53 49 56 SQLITE_RECURSIV
22f60 45 20 20 20 20 20 20 20 20 20 20 20 20 33 33 20 E 33
22f70 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 /* NULL
22f80 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
22f90 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 */../*.** C
22fa0 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 API3REF: Tracing
22fb0 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 And Profiling F
22fc0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 unctions.** METH
22fd0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a OD: sqlite3.**.*
22fe0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
22ff0 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 register callba
23000 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 ck functions tha
23010 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f t can be used fo
23020 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 r.** tracing and
23030 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 profiling the e
23040 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 xecution of SQL
23050 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a statements..**.*
23060 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 * ^The callback
23070 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 function registe
23080 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 red by sqlite3_t
23090 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 race() is invoke
230a0 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 d at.** various
230b0 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 times when an SQ
230c0 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 L statement is b
230d0 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c eing run by [sql
230e0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a ite3_step()]..**
230f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 ^The sqlite3_tr
23100 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 ace() callback i
23110 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 s invoked with a
23120 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 UTF-8 rendering
23130 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 of the.** SQL s
23140 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 tatement text as
23150 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 the statement f
23160 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 irst begins exec
23170 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 uting..** ^(Addi
23180 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 tional sqlite3_t
23190 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 race() callbacks
231a0 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 might occur.**
231b0 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65 as each triggere
231c0 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 d subprogram is
231d0 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 entered. The ca
231e0 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 llbacks for trig
231f0 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 gers.** contain
23200 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d a UTF-8 SQL comm
23210 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 ent that identif
23220 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e ies the trigger.
23230 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 )^.**.** The [SQ
23240 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f LITE_TRACE_SIZE_
23250 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 LIMIT] compile-t
23260 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 ime option can b
23270 65 20 75 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a e used to limit.
23280 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 ** the length of
23290 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 [bound paramete
232a0 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 r] expansion in
232b0 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20 73 71 the output of sq
232c0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a lite3_trace()..*
232d0 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 *.** ^The callba
232e0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 ck function regi
232f0 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 stered by sqlite
23300 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 3_profile() is i
23310 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 nvoked.** as eac
23320 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 h SQL statement
23330 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 finishes. ^The
23340 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b profile callback
23350 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 contains.** the
23360 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d original statem
23370 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 ent text and an
23380 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c estimate of wall
23390 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f -clock time.** o
233a0 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 f how long that
233b0 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 statement took t
233c0 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f o run. ^The pro
233d0 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a file callback.**
233e0 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 time is in unit
233f0 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 s of nanoseconds
23400 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 , however the cu
23410 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 rrent implementa
23420 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 tion.** is only
23430 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 capable of milli
23440 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f second resolutio
23450 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 n so the six lea
23460 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a st significant.*
23470 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 * digits in the
23480 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 time are meaning
23490 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 less. Future ve
234a0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
234b0 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 .** might provid
234c0 65 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 e greater resolu
234d0 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 tion on the prof
234e0 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 iler callback.
234f0 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 The.** sqlite3_p
23500 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f rofile() functio
23510 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 n is considered
23520 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 experimental and
23530 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 is.** subject t
23540 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 o change in futu
23550 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 re versions of S
23560 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 QLite..*/.SQLITE
23570 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 _API void *SQLIT
23580 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
23590 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 3_trace(sqlite3*
235a0 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 , void(*xTrace)(
235b0 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 void*,const char
235c0 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 *), void*);.SQLI
235d0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 TE_API SQLITE_EX
235e0 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 PERIMENTAL void
235f0 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 *SQLITE_STDCALL
23600 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 sqlite3_profile(
23610 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 sqlite3*,. voi
23620 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 d(*xProfile)(voi
23630 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 d*,const char*,s
23640 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 qlite3_uint64),
23650 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 void*);../*.** C
23660 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 API3REF: Query P
23670 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b rogress Callback
23680 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c s.** METHOD: sql
23690 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ite3.**.** ^The
236a0 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 sqlite3_progress
236b0 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 _handler(D,N,X,P
236c0 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 ) interface caus
236d0 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a es the callback.
236e0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f ** function X to
236f0 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 be invoked peri
23700 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 odically during
23710 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c long running cal
23720 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 ls to.** [sqlite
23730 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 3_exec()], [sqli
23740 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 te3_step()] and
23750 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 [sqlite3_get_tab
23760 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 le()] for.** dat
23770 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
23780 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 D. An example
23790 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 use for this.**
237a0 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 interface is to
237b0 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74 keep a GUI updat
237c0 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 ed during a larg
237d0 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e e query..**.** ^
237e0 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 The parameter P
237f0 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 is passed throug
23800 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 h as the only pa
23810 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a rameter to the .
23820 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 ** callback func
23830 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 tion X. ^The pa
23840 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 rameter N is the
23850 20 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d approximate num
23860 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 ber of .** [virt
23870 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 ual machine inst
23880 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 ructions] that a
23890 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 re evaluated bet
238a0 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a ween successive.
238b0 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f ** invocations o
238c0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 f the callback X
238d0 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 . ^If N is less
238e0 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74 than one then t
238f0 68 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68 he progress.** h
23900 61 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62 6c andler is disabl
23910 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 ed..**.** ^Only
23920 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 a single progres
23930 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 s handler may be
23940 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 defined at one
23950 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 time per.** [dat
23960 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
23970 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77 ]; setting a new
23980 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 progress handle
23990 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a r cancels the.**
239a0 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 old one. ^Sett
239b0 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20 ing parameter X
239c0 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 to NULL disables
239d0 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 the progress ha
239e0 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 ndler..** ^The p
239f0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 rogress handler
23a00 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 is also disabled
23a10 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f by setting N to
23a20 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a a value less.**
23a30 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e than 1..**.** ^
23a40 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 If the progress
23a50 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
23a60 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f non-zero, the o
23a70 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 peration is.** i
23a80 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 nterrupted. Thi
23a90 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 s feature can be
23aa0 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 used to impleme
23ab0 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 nt a.** "Cancel"
23ac0 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 button on a GUI
23ad0 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 progress dialog
23ae0 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 box..**.** The
23af0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 progress handler
23b00 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e callback must n
23b10 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 ot do anything t
23b20 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a hat will modify.
23b30 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ** the database
23b40 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 connection that
23b50 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 invoked the prog
23b60 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a ress handler..**
23b70 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 Note that [sqli
23b80 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
23b90 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 ] and [sqlite3_s
23ba0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 tep()] both modi
23bb0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 fy their.** data
23bc0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
23bd0 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 for the meaning
23be0 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 of "modify" in
23bf0 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a this paragraph..
23c00 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 **.*/.SQLITE_API
23c10 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 void SQLITE_STD
23c20 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 6f CALL sqlite3_pro
23c30 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 gress_handler(sq
23c40 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 lite3*, int, int
23c50 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 (*)(void*), void
23c60 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
23c70 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e REF: Opening A N
23c80 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e ew Database Conn
23c90 65 63 74 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52 ection.** CONSTR
23ca0 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a UCTOR: sqlite3.*
23cb0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 *.** ^These rout
23cc0 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c ines open an SQL
23cd0 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c ite database fil
23ce0 65 20 61 73 20 73 70 65 63 69 66 69 65 64 20 62 e as specified b
23cf0 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 y the .** filena
23d00 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 me argument. ^Th
23d10 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d e filename argum
23d20 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 ent is interpret
23d30 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a ed as UTF-8 for.
23d40 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 ** sqlite3_open(
23d50 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 ) and sqlite3_op
23d60 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 en_v2() and as U
23d70 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 TF-16 in the nat
23d80 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 ive byte.** orde
23d90 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 r for sqlite3_op
23da0 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 en16(). ^(A [dat
23db0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
23dc0 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 ] handle is usua
23dd0 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 lly.** returned
23de0 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 in *ppDb, even i
23df0 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 f an error occur
23e00 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 s. The only exc
23e10 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a eption is that.*
23e20 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 * if SQLite is u
23e30 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 nable to allocat
23e40 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 e memory to hold
23e50 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f the [sqlite3] o
23e60 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c bject,.** a NULL
23e70 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e will be written
23e80 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 into *ppDb inst
23e90 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 ead of a pointer
23ea0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
23eb0 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e ].** object.)^ ^
23ec0 28 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 (If the database
23ed0 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f is opened (and/
23ee0 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63 63 or created) succ
23ef0 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a essfully, then.*
23f00 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 * [SQLITE_OK] is
23f10 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 returned. Othe
23f20 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 rwise an [error
23f30 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 code] is returne
23f40 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 d.)^ ^The.** [sq
23f50 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 lite3_errmsg()]
23f60 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d or [sqlite3_errm
23f70 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 sg16()] routines
23f80 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
23f90 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 obtain.** an Eng
23fa0 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 lish language de
23fb0 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 scription of the
23fc0 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 error following
23fd0 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e a failure of an
23fe0 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 y.** of the sqli
23ff0 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 te3_open() routi
24000 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 nes..**.** ^The
24010 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 default encoding
24020 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 66 will be UTF-8 f
24030 6f 72 20 64 61 74 61 62 61 73 65 73 20 63 72 65 or databases cre
24040 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 73 71 ated using.** sq
24050 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 lite3_open() or
24060 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
24070 29 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c 74 ). ^The default
24080 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 64 61 encoding for da
24090 74 61 62 61 73 65 73 0a 2a 2a 20 63 72 65 61 74 tabases.** creat
240a0 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 ed using sqlite3
240b0 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c 6c 20 62 _open16() will b
240c0 65 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 e UTF-16 in the
240d0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 native byte orde
240e0 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 r..**.** Whether
240f0 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 or not an error
24100 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 occurs when it
24110 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 is opened, resou
24120 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 rces.** associat
24130 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 ed with the [dat
24140 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
24150 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 ] handle should
24160 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a be released by.*
24170 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 * passing it to
24180 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 [sqlite3_close()
24190 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 ] when it is no
241a0 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e longer required.
241b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
241c0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 e3_open_v2() int
241d0 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b erface works lik
241e0 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 e sqlite3_open()
241f0 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 .** except that
24200 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 it accepts two a
24210 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 dditional parame
24220 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f ters for additio
24230 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f nal control.** o
24240 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 ver the new data
24250 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e base connection.
24260 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 ^(The flags pa
24270 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 rameter to.** sq
24280 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
24290 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a can take one of.
242a0 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 ** the following
242b0 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f three values, o
242c0 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e ptionally combin
242d0 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 ed with the .**
242e0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d [SQLITE_OPEN_NOM
242f0 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f UTEX], [SQLITE_O
24300 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 PEN_FULLMUTEX],
24310 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 [SQLITE_OPEN_SHA
24320 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 REDCACHE],.** [S
24330 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 QLITE_OPEN_PRIVA
24340 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 TECACHE], and/or
24350 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 [SQLITE_OPEN_UR
24360 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a I] flags:)^.**.*
24370 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e * <dl>.** ^(<dt>
24380 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 [SQLITE_OPEN_REA
24390 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c DONLY]</dt>.** <
243a0 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 dd>The database
243b0 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 is opened in rea
243c0 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 d-only mode. If
243d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f the database do
243e0 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 es not.** alread
243f0 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f y exist, an erro
24400 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f r is returned.</
24410 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 dd>)^.**.** ^(<d
24420 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 t>[SQLITE_OPEN_R
24430 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a EADWRITE]</dt>.*
24440 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 * <dd>The databa
24450 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 se is opened for
24460 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 reading and wri
24470 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 ting if possible
24480 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 , or reading.**
24490 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 only if the file
244a0 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 is write protec
244b0 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 ted by the opera
244c0 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e ting system. In
244d0 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 either.** case
244e0 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 the database mus
244f0 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c t already exist,
24500 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 otherwise an er
24510 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e ror is returned.
24520 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 </dd>)^.**.** ^(
24530 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e <dt>[SQLITE_OPEN
24540 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 _READWRITE] | [S
24550 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 QLITE_OPEN_CREAT
24560 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 E]</dt>.** <dd>T
24570 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f he database is o
24580 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e pened for readin
24590 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 g and writing, a
245a0 6e 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66 nd is created if
245b0 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 .** it does not
245c0 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 already exist. T
245d0 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76 his is the behav
245e0 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 ior that is alwa
245f0 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 ys used for.** s
24600 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e qlite3_open() an
24610 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 d sqlite3_open16
24620 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f ().</dd>)^.** </
24630 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 dl>.**.** If the
24640 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 3rd parameter t
24650 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 o sqlite3_open_v
24660 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 2() is not one o
24670 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 f the.** combina
24680 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 tions shown abov
24690 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d e optionally com
246a0 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72 bined with other
246b0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e .** [SQLITE_OPEN
246c0 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 _READONLY | SQLI
246d0 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a TE_OPEN_* bits].
246e0 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 ** then the beha
246f0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 vior is undefine
24700 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 d..**.** ^If the
24710 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f [SQLITE_OPEN_NO
24720 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 MUTEX] flag is s
24730 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 et, then the dat
24740 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
24750 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 .** opens in the
24760 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 multi-thread [t
24770 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 hreading mode] a
24780 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 s long as the si
24790 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d ngle-thread.** m
247a0 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e ode has not been
247b0 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d set at compile-
247c0 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 time or start-ti
247d0 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 me. ^If the.**
247e0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c [SQLITE_OPEN_FUL
247f0 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 LMUTEX] flag is
24800 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 set then the dat
24810 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
24820 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 opens.** in the
24830 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 serialized [thr
24840 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c eading mode] unl
24850 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 ess single-threa
24860 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 d was.** previou
24870 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 sly selected at
24880 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 compile-time or
24890 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e start-time..** ^
248a0 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e The [SQLITE_OPEN
248b0 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c _SHAREDCACHE] fl
248c0 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 ag causes the da
248d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
248e0 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 n to be.** eligi
248f0 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 ble to use [shar
24900 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 ed cache mode],
24910 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 regardless of wh
24920 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 ether or not sha
24930 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 red.** cache is
24940 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 enabled using [s
24950 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 qlite3_enable_sh
24960 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 ared_cache()].
24970 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ^The.** [SQLITE_
24980 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 OPEN_PRIVATECACH
24990 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 E] flag causes t
249a0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
249b0 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a ection to not.**
249c0 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 participate in
249d0 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f [shared cache mo
249e0 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 de] even if it i
249f0 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a s enabled..**.**
24a00 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 ^The fourth par
24a10 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
24a20 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 3_open_v2() is t
24a30 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a he name of the.*
24a40 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 * [sqlite3_vfs]
24a50 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 object that defi
24a60 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e nes the operatin
24a70 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 g system interfa
24a80 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e ce that.** the n
24a90 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ew database conn
24aa0 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 ection should us
24ab0 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 e. ^If the four
24ac0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a th parameter is.
24ad0 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ** a NULL pointe
24ae0 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 r then the defau
24af0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d lt [sqlite3_vfs]
24b00 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e object is used.
24b10 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 .**.** ^If the f
24b20 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d ilename is ":mem
24b30 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 ory:", then a pr
24b40 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 ivate, temporary
24b50 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 in-memory datab
24b60 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 ase.** is create
24b70 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 d for the connec
24b80 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d tion. ^This in-
24b90 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 memory database
24ba0 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e will vanish when
24bb0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 .** the database
24bc0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 connection is c
24bd0 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 losed. Future v
24be0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
24bf0 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 e might.** make
24c00 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 use of additiona
24c10 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 l special filena
24c20 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 mes that begin w
24c30 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 ith the ":" char
24c40 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 acter..** It is
24c50 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 recommended that
24c60 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 when a database
24c70 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c filename actual
24c80 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 ly does begin wi
24c90 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 th.** a ":" char
24ca0 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 acter you should
24cb0 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 prefix the file
24cc0 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 name with a path
24cd0 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 name such as.**
24ce0 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d "./" to avoid am
24cf0 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e biguity..**.** ^
24d00 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 If the filename
24d10 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 is an empty stri
24d20 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 ng, then a priva
24d30 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a te, temporary.**
24d40 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 on-disk databas
24d50 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 e will be create
24d60 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 d. ^This privat
24d70 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 e database will
24d80 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 be.** automatica
24d90 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 lly deleted as s
24da0 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 oon as the datab
24db0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 ase connection i
24dc0 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 s closed..**.**
24dd0 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 [[URI filenames
24de0 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 in sqlite3_open(
24df0 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 )]] <h3>URI File
24e00 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a names</h3>.**.**
24e10 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 ^If [URI filena
24e20 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69 me] interpretati
24e30 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 on is enabled, a
24e40 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 nd the filename
24e50 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 argument.** begi
24e60 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c ns with "file:",
24e70 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 then the filena
24e80 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 me is interprete
24e90 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49 d as a URI. ^URI
24ea0 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 .** filename int
24eb0 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 erpretation is e
24ec0 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53 nabled if the [S
24ed0 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 QLITE_OPEN_URI]
24ee0 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 flag is.** set i
24ef0 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 n the fourth arg
24f00 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 ument to sqlite3
24f10 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 _open_v2(), or i
24f20 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e f it has.** been
24f30 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c enabled globall
24f40 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c y using the [SQL
24f50 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 ITE_CONFIG_URI]
24f60 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a option with the.
24f70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 ** [sqlite3_conf
24f80 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 ig()] method or
24f90 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 by the [SQLITE_U
24fa0 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d SE_URI] compile-
24fb0 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 time option..**
24fc0 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 As of SQLite ver
24fd0 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 sion 3.7.7, URI
24fe0 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 filename interpr
24ff0 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 etation is turne
25000 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 d off.** by defa
25010 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 ult, but future
25020 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 releases of SQLi
25030 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 te might enable
25040 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 URI filename.**
25050 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 interpretation b
25060 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 y default. See
25070 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d "[URI filenames]
25080 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c " for additional
25090 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e .** information.
250a0 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e .**.** URI filen
250b0 61 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 20 ames are parsed
250c0 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 according to RFC
250d0 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 3986. ^If the U
250e0 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a RI contains an.*
250f0 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 * authority, the
25100 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 n it must be eit
25110 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 her an empty str
25120 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e ing or the strin
25130 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 g .** "localhost
25140 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f ". ^If the autho
25150 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 rity is not an e
25160 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 mpty string or "
25170 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a localhost", an .
25180 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 ** error is retu
25190 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c rned to the call
251a0 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e er. ^The fragmen
251b0 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 t component of a
251c0 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 URI, if .** pre
251d0 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 sent, is ignored
251e0 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 ..**.** ^SQLite
251f0 75 73 65 73 20 74 68 65 20 70 61 74 68 20 63 6f uses the path co
25200 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 mponent of the U
25210 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f RI as the name o
25220 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a f the disk file.
25230 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e ** which contain
25240 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 s the database.
25250 5e 49 66 20 74 68 65 20 70 61 74 68 20 62 65 67 ^If the path beg
25260 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 ins with a '/' c
25270 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 haracter, .** th
25280 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 en it is interpr
25290 65 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c eted as an absol
252a0 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 ute path. ^If th
252b0 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 e path does not
252c0 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 begin .** with a
252d0 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 '/' (meaning th
252e0 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 at the authority
252f0 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 section is omit
25300 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 ted from the URI
25310 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 ).** then the pa
25320 74 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 th is interprete
25330 64 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 d as a relative
25340 70 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 path. .** ^(On w
25350 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 indows, the firs
25360 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 t component of a
25370 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 n absolute path
25380 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 .** is a drive s
25390 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e pecification (e.
253a0 67 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a g. "C:").)^.**.*
253b0 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65 * [[core URI que
253c0 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a ry parameters]].
253d0 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d ** The query com
253e0 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 ponent of a URI
253f0 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 may contain para
25400 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20 meters that are
25410 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 interpreted.** e
25420 69 74 68 65 72 20 62 79 20 53 51 4c 69 74 65 20 ither by SQLite
25430 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 itself, or by a
25440 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 [VFS | custom VF
25450 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e S implementation
25460 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 ]..** SQLite and
25470 20 69 74 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56 its built-in [V
25480 46 53 65 73 5d 20 69 6e 74 65 72 70 72 65 74 20 FSes] interpret
25490 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 the.** following
254a0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 query parameter
254b0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a s:.**.** <ul>.**
254c0 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f <li> <b>vfs</
254d0 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70 b>: ^The "vfs" p
254e0 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 arameter may be
254f0 75 73 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 used to specify
25500 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 the name of.**
25510 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20 a VFS object
25520 74 68 61 74 20 70 72 6f 76 69 64 65 73 20 74 68 that provides th
25530 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 e operating syst
25540 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 em interface tha
25550 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 t should.**
25560 62 65 20 75 73 65 64 20 74 6f 20 61 63 63 65 73 be used to acces
25570 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 s the database f
25580 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 ile on disk. ^If
25590 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 this option is
255a0 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e set to.** an
255b0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68 empty string th
255c0 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62 e default VFS ob
255d0 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53 ject is used. ^S
255e0 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b pecifying an unk
255f0 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 nown.** VFS
25600 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 is an error. ^If
25610 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
25620 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 () is used and t
25630 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 he vfs option is
25640 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c .** present,
25650 20 74 68 65 6e 20 74 68 65 20 56 46 53 20 73 70 then the VFS sp
25660 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f ecified by the o
25670 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 ption takes prec
25680 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 edence over.**
25690 20 20 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 the value pas
256a0 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 sed as the fourt
256b0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 h parameter to s
256c0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
256d0 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c ..**.** <li> <
256e0 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 b>mode</b>: ^(Th
256f0 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 e mode parameter
25700 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 may be set to e
25710 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22 ither "ro", "rw"
25720 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20 ,.** "rwc",
25730 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 or "memory". Att
25740 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 empting to set i
25750 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 t to any other v
25760 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 alue is.** a
25770 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 n error)^. .**
25780 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 ^If "ro" is s
25790 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 pecified, then t
257a0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f he database is o
257b0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f pened for read-o
257c0 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 nly .** acce
257d0 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 ss, just as if t
257e0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f he [SQLITE_OPEN_
257f0 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 READONLY] flag h
25800 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 ad been set in t
25810 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 he .** third
25820 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c argument to sql
25830 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 ite3_open_v2().
25840 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 ^If the mode opt
25850 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a ion is set to .*
25860 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e * "rw", then
25870 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 the database is
25880 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 opened for read
25890 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 -write (but not
258a0 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 create) .**
258b0 61 63 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 access, as if SQ
258c0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 LITE_OPEN_READWR
258d0 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c ITE (but not SQL
258e0 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 ITE_OPEN_CREATE)
258f0 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 had .** bee
25900 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 n set. ^Value "r
25910 77 63 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e wc" is equivalen
25920 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 t to setting bot
25930 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 h .** SQLITE
25940 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 _OPEN_READWRITE
25950 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f and SQLITE_OPEN_
25960 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65 CREATE. ^If the
25970 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a mode option is.
25980 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d ** set to "m
25990 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75 emory" then a pu
259a0 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 re [in-memory da
259b0 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76 tabase] that nev
259c0 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 er reads.**
259d0 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64 or writes from d
259e0 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74 isk is used. ^It
259f0 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 is an error to
25a00 73 70 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 specify a value
25a10 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d for.** the m
25a20 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 ode parameter th
25a30 61 74 20 69 73 20 6c 65 73 73 20 72 65 73 74 72 at is less restr
25a40 69 63 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 ictive than that
25a50 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a specified by.**
25a60 20 20 20 20 20 74 68 65 20 66 6c 61 67 73 20 70 the flags p
25a70 61 73 73 65 64 20 69 6e 20 74 68 65 20 74 68 69 assed in the thi
25a80 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 rd parameter to
25a90 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
25aa0 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 )..**.** <li>
25ab0 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 <b>cache</b>: ^T
25ac0 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 he cache paramet
25ad0 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f er may be set to
25ae0 20 65 69 74 68 65 72 20 22 73 68 61 72 65 64 22 either "shared"
25af0 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 or.** "priv
25b00 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 ate". ^Setting i
25b10 74 20 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 t to "shared" is
25b20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 equivalent to s
25b30 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 etting the.**
25b40 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 SQLITE_OPEN_SH
25b50 41 52 45 44 43 41 43 48 45 20 62 69 74 20 69 6e AREDCACHE bit in
25b60 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d the flags argum
25b70 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a ent passed to.**
25b80 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 sqlite3_ope
25b90 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 n_v2(). ^Setting
25ba0 20 74 68 65 20 63 61 63 68 65 20 70 61 72 61 6d the cache param
25bb0 65 74 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 eter to "private
25bc0 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 " is .** equ
25bd0 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 ivalent to setti
25be0 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 ng the SQLITE_OP
25bf0 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 EN_PRIVATECACHE
25c00 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 bit..** ^If
25c10 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
25c20 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 ) is used and th
25c30 65 20 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 e "cache" parame
25c40 74 65 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 ter is present i
25c50 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 n.** a URI f
25c60 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c ilename, its val
25c70 75 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 ue overrides any
25c80 20 62 65 68 61 76 69 6f 72 20 72 65 71 75 65 73 behavior reques
25c90 74 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a ted by setting.*
25ca0 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 * SQLITE_OPE
25cb0 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 6f N_PRIVATECACHE o
25cc0 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 r SQLITE_OPEN_SH
25cd0 41 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a AREDCACHE flag..
25ce0 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 **.** <li> <b>p
25cf0 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73 sow</b>: ^The ps
25d00 6f 77 20 70 61 72 61 6d 65 74 65 72 20 69 6e 64 ow parameter ind
25d10 69 63 61 74 65 73 20 77 68 65 74 68 65 72 20 6f icates whether o
25d20 72 20 6e 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20 r not the.**
25d30 20 5b 70 6f 77 65 72 73 61 66 65 20 6f 76 65 72 [powersafe over
25d40 77 72 69 74 65 5d 20 70 72 6f 70 65 72 74 79 20 write] property
25d50 64 6f 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 does or does not
25d60 20 61 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a apply to the.**
25d70 20 20 20 20 20 73 74 6f 72 61 67 65 20 6d 65 64 storage med
25d80 69 61 20 6f 6e 20 77 68 69 63 68 20 74 68 65 20 ia on which the
25d90 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 72 65 database file re
25da0 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c sides..**.** <l
25db0 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e i> <b>nolock</b>
25dc0 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 : ^The nolock pa
25dd0 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f rameter is a boo
25de0 6c 65 61 6e 20 71 75 65 72 79 20 70 61 72 61 6d lean query param
25df0 65 74 65 72 0a 2a 2a 20 20 20 20 20 77 68 69 63 eter.** whic
25e00 68 20 69 66 20 73 65 74 20 64 69 73 61 62 6c 65 h if set disable
25e10 73 20 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 s file locking i
25e20 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e n rollback journ
25e30 61 6c 20 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a al modes. This.
25e40 2a 2a 20 20 20 20 20 69 73 20 75 73 65 66 75 6c ** is useful
25e50 20 66 6f 72 20 61 63 63 65 73 73 69 6e 67 20 61 for accessing a
25e60 20 64 61 74 61 62 61 73 65 20 6f 6e 20 61 20 66 database on a f
25e70 69 6c 65 73 79 73 74 65 6d 20 74 68 61 74 20 64 ilesystem that d
25e80 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 oes not.** s
25e90 75 70 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 upport locking.
25ea0 20 43 61 75 74 69 6f 6e 3a 20 20 44 61 74 61 62 Caution: Datab
25eb0 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d ase corruption m
25ec0 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 74 ight result if t
25ed0 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72 wo.** or mor
25ee0 65 20 70 72 6f 63 65 73 73 65 73 20 77 72 69 74 e processes writ
25ef0 65 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 e to the same da
25f00 74 61 62 61 73 65 20 61 6e 64 20 61 6e 79 20 6f tabase and any o
25f10 6e 65 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20 ne of those.**
25f20 20 20 20 70 72 6f 63 65 73 73 65 73 20 75 73 65 processes use
25f30 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a s nolock=1..**.*
25f40 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 * <li> <b>immut
25f50 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 able</b>: ^The i
25f60 6d 6d 75 74 61 62 6c 65 20 70 61 72 61 6d 65 74 mmutable paramet
25f70 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 er is a boolean
25f80 71 75 65 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 query.** par
25f90 61 6d 65 74 65 72 20 74 68 61 74 20 69 6e 64 69 ameter that indi
25fa0 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20 64 cates that the d
25fb0 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 atabase file is
25fc0 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 stored on.**
25fd0 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 read-only media
25fe0 2e 20 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62 . ^When immutab
25ff0 6c 65 20 69 73 20 73 65 74 2c 20 53 51 4c 69 74 le is set, SQLit
26000 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 e assumes that t
26010 68 65 0a 2a 2a 20 20 20 20 20 64 61 74 61 62 61 he.** databa
26020 73 65 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 se file cannot b
26030 65 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 e changed, even
26040 62 79 20 61 20 70 72 6f 63 65 73 73 20 77 69 74 by a process wit
26050 68 20 68 69 67 68 65 72 0a 2a 2a 20 20 20 20 20 h higher.**
26060 70 72 69 76 69 6c 65 67 65 2c 20 61 6e 64 20 73 privilege, and s
26070 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 o the database i
26080 73 20 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e s opened read-on
26090 6c 79 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 ly and all locki
260a0 6e 67 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63 68 ng.** and ch
260b0 61 6e 67 65 20 64 65 74 65 63 74 69 6f 6e 20 69 ange detection i
260c0 73 20 64 69 73 61 62 6c 65 64 2e 20 20 43 61 75 s disabled. Cau
260d0 74 69 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74 68 tion: Setting th
260e0 65 20 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 e immutable.**
260f0 20 20 20 70 72 6f 70 65 72 74 79 20 6f 6e 20 61 property on a
26100 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 database file t
26110 68 61 74 20 64 6f 65 73 20 69 6e 20 66 61 63 74 hat does in fact
26120 20 63 68 61 6e 67 65 20 63 61 6e 20 72 65 73 75 change can resu
26130 6c 74 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63 lt.** in inc
26140 6f 72 72 65 63 74 20 71 75 65 72 79 20 72 65 73 orrect query res
26150 75 6c 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c ults and/or [SQL
26160 49 54 45 5f 43 4f 52 52 55 50 54 5d 20 65 72 72 ITE_CORRUPT] err
26170 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20 ors..** See
26180 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f also: [SQLITE_IO
26190 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a CAP_IMMUTABLE]..
261a0 2a 2a 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 ** .** </u
261b0 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 l>.**.** ^Specif
261c0 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 ying an unknown
261d0 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 parameter in the
261e0 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 query component
261f0 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 of a URI is not
26200 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 an.** error. F
26210 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f uture versions o
26220 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 f SQLite might u
26230 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 nderstand additi
26240 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 onal query.** pa
26250 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 rameters. See "
26260 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 [query parameter
26270 73 20 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d s with special m
26280 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 eaning to SQLite
26290 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 ]" for.** additi
262a0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e onal information
262b0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 ..**.** [[URI fi
262c0 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d lename examples]
262d0 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 ] <h3>URI filena
262e0 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e me examples</h3>
262f0 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f .**.** <table bo
26300 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 rder="1" align=c
26310 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e enter cellpaddin
26320 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e g=5>.** <tr><th>
26330 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c URI filenames <
26340 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c th> Results.** <
26350 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 tr><td> file:dat
26360 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 a.db <td> .**
26370 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 Open the
26380 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 file "data.db" i
26390 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 n the current di
263a0 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e rectory..** <tr>
263b0 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f <td> file:/home/
263c0 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e fred/data.db<br>
263d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c .** fil
263e0 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 e:///home/fred/d
263f0 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 ata.db <br> .**
26400 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f file://
26410 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 localhost/home/f
26420 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e red/data.db <br>
26430 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 <td> .**
26440 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 Open the data
26450 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 base file "/home
26460 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a /fred/data.db"..
26470 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 ** <tr><td> file
26480 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 ://darkstar/home
26490 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 /fred/data.db <t
264a0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 d> .**
264b0 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 An error. "darks
264c0 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 tar" is not a re
264d0 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 cognized authori
264e0 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 ty..** <tr><td s
264f0 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 tyle="white-spac
26500 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 e:nowrap"> .**
26510 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f file:///
26520 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 C:/Documents%20a
26530 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 nd%20Settings/fr
26540 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e ed/Desktop/data.
26550 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 db.** <td> W
26560 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 indows only: Ope
26570 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 n the file "data
26580 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 .db" on fred's d
26590 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a esktop on drive.
265a0 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 ** C:.
265b0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 25 32 Note that the %2
265c0 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 0 escaping in th
265d0 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f is example is no
265e0 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 t strictly .**
265f0 20 20 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 necessar
26600 79 20 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 y - space charac
26610 74 65 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 ters can be used
26620 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 literally.**
26630 20 20 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 in URI fi
26640 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e lenames..** <tr>
26650 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 <td> file:data.d
26660 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d b?mode=ro&cache=
26670 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a private <td> .**
26680 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 Open f
26690 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e ile "data.db" in
266a0 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 the current dir
266b0 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d ectory for read-
266c0 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 only access..**
266d0 20 20 20 20 20 20 20 20 20 52 65 67 61 72 64 6c Regardl
266e0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f ess of whether o
266f0 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 r not shared-cac
26700 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c he mode is enabl
26710 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 ed by.**
26720 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 default, use a
26730 20 70 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a private cache..
26740 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 ** <tr><td> file
26750 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 :/home/fred/data
26760 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74 .db?vfs=unix-dot
26770 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 file <td>.**
26780 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 Open file
26790 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 "/home/fred/data
267a0 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20 73 70 .db". Use the sp
267b0 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d ecial VFS "unix-
267c0 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20 dotfile".**
267d0 20 20 20 20 20 74 68 61 74 20 75 73 65 73 20 64 that uses d
267e0 6f 74 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61 63 ot-files in plac
267f0 65 20 6f 66 20 70 6f 73 69 78 20 61 64 76 69 73 e of posix advis
26800 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 ory locking..**
26810 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 <tr><td> file:da
26820 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f ta.db?mode=reado
26830 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 nly <td> .**
26840 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 An error.
26850 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f "readonly" is no
26860 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e t a valid option
26870 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20 for the "mode"
26880 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f parameter..** </
26890 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 table>.**.** ^UR
268a0 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 I hexadecimal es
268b0 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 28 cape sequences (
268c0 25 48 48 29 20 61 72 65 20 73 75 70 70 6f 72 74 %HH) are support
268d0 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 70 61 ed within the pa
268e0 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 th and.** query
268f0 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 components of a
26900 55 52 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d URI. A hexadecim
26910 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e al escape sequen
26920 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 ce consists of a
26930 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e .** percent sign
26940 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 - "%" - followe
26950 64 20 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f d by exactly two
26960 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67 hexadecimal dig
26970 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 its .** specifyi
26980 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 ng an octet valu
26990 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70 e. ^Before the p
269a0 61 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d ath or query com
269b0 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 ponents of a.**
269c0 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 URI filename are
269d0 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68 interpreted, th
269e0 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75 ey are encoded u
269f0 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61 sing UTF-8 and a
26a00 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d ll .** hexadecim
26a10 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e al escape sequen
26a20 63 65 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 ces replaced by
26a30 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f a single byte co
26a40 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 ntaining the.**
26a50 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 corresponding oc
26a60 74 65 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f tet. If this pro
26a70 63 65 73 73 20 67 65 6e 65 72 61 74 65 73 20 61 cess generates a
26a80 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 n invalid UTF-8
26a90 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 encoding,.** the
26aa0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 results are und
26ab0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 efined..**.** <b
26ac0 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 >Note to Windows
26ad0 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 users:</b> The
26ae0 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 encoding used f
26af0 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 or the filename
26b00 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 argument.** of s
26b10 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e qlite3_open() an
26b20 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 d sqlite3_open_v
26b30 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 2() must be UTF-
26b40 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 8, not whatever.
26b50 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 ** codepage is c
26b60 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 urrently defined
26b70 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e . Filenames con
26b80 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 taining internat
26b90 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 ional.** charact
26ba0 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 ers must be conv
26bb0 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 erted to UTF-8 p
26bc0 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 rior to passing
26bd0 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c them into.** sql
26be0 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 ite3_open() or s
26bf0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
26c00 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 ..**.** <b>Note
26c10 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 to Windows Runti
26c20 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 me users:</b> T
26c30 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 he temporary dir
26c40 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 ectory must be s
26c50 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 et.** prior to c
26c60 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f alling sqlite3_o
26c70 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 pen() or sqlite3
26c80 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 _open_v2(). Oth
26c90 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a erwise, various.
26ca0 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68 61 74 ** features that
26cb0 20 72 65 71 75 69 72 65 20 74 68 65 20 75 73 65 require the use
26cc0 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 of temporary fi
26cd0 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a les may fail..**
26ce0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 .** See also: [s
26cf0 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 qlite3_temp_dire
26d00 63 74 6f 72 79 5d 0a 2a 2f 0a 53 51 4c 49 54 45 ctory].*/.SQLITE
26d10 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f _API int SQLITE_
26d20 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
26d30 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 open(. const ch
26d40 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 ar *filename,
26d50 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 /* Database file
26d60 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a name (UTF-8) */.
26d70 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 sqlite3 **ppDb
26d80 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 /* OUT
26d90 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 : SQLite db hand
26da0 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f le */.);.SQLITE_
26db0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 API int SQLITE_S
26dc0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f TDCALL sqlite3_o
26dd0 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 pen16(. const v
26de0 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 oid *filename,
26df0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c /* Database fil
26e00 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a ename (UTF-16) *
26e10 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 /. sqlite3 **pp
26e20 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f Db /* O
26e30 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 UT: SQLite db ha
26e40 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 ndle */.);.SQLIT
26e50 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
26e60 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
26e70 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 _open_v2(. cons
26e80 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 t char *filename
26e90 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 , /* Database
26ea0 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 filename (UTF-8)
26eb0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a */. sqlite3 **
26ec0 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a ppDb, /*
26ed0 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 OUT: SQLite db
26ee0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 handle */. int
26ef0 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 flags,
26f00 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a /* Flags */.
26f10 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 const char *zV
26f20 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d fs /* Nam
26f30 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 e of VFS module
26f40 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a to use */.);../*
26f50 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 .** CAPI3REF: Ob
26f60 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 tain Values For
26f70 55 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a URI Parameters.*
26f80 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75 *.** These are u
26f90 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c tility routines,
26fa0 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69 useful to VFS i
26fb0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 mplementations,
26fc0 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f that check.** to
26fd0 20 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61 see if a databa
26fe0 73 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52 se file was a UR
26ff0 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 I that contained
27000 20 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72 a specific quer
27010 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c y .** parameter,
27020 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69 and if so obtai
27030 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 ns the value of
27040 74 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d that query param
27050 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 eter..**.** If F
27060 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 is the database
27070 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 filename pointe
27080 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 r passed into th
27090 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 e xOpen() method
270a0 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d of .** a VFS im
270b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 plementation whe
270c0 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 n the flags para
270d0 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 meter to xOpen()
270e0 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 has one or .**
270f0 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c more of the [SQL
27100 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 ITE_OPEN_URI] or
27110 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 [SQLITE_OPEN_MA
27120 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20 IN_DB] bits set
27130 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 and.** P is the
27140 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72 name of the quer
27150 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 y parameter, the
27160 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 n.** sqlite3_uri
27170 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 _parameter(F,P)
27180 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 returns the valu
27190 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 e of the P.** pa
271a0 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78 rameter if it ex
271b0 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 ists or a NULL p
271c0 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73 ointer if P does
271d0 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61 not appear as a
271e0 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d .** query param
271f0 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 eter on F. If P
27200 20 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61 is a query para
27210 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 meter of F.** ha
27220 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61 s no explicit va
27230 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 lue, then sqlite
27240 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 3_uri_parameter(
27250 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 F,P) returns.**
27260 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
27270 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a empty string..**
27280 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
27290 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c uri_boolean(F,P,
272a0 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d B) routine assum
272b0 65 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62 es that P is a b
272c0 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 oolean.** parame
272d0 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 ter and returns
272e0 74 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73 true (1) or fals
272f0 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20 e (0) according
27300 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 to the value.**
27310 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74 of P. The sqlit
27320 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 e3_uri_boolean(F
27330 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65 ,P,B) routine re
27340 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69 turns true (1) i
27350 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f f the.** value o
27360 66 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 f query paramete
27370 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 r P is one of "y
27380 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 es", "true", or
27390 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 "on" in any.** c
273a0 61 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61 ase or if the va
273b0 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 lue begins with
273c0 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 a non-zero numbe
273d0 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 r. The .** sqli
273e0 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 te3_uri_boolean(
273f0 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 F,P,B) routines
27400 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30 returns false (0
27410 29 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f ) if the value o
27420 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d f.** query param
27430 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 eter P is one of
27440 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 "no", "false",
27450 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 or "off" in any
27460 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 case or.** if th
27470 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 e value begins w
27480 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 ith a numeric ze
27490 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74 ro. If P is not
274a0 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 a query.** para
274b0 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 meter on F or if
274c0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 the value of P
274d0 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 is does not matc
274e0 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 h any of the.**
274f0 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 above, then sqli
27500 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 te3_uri_boolean(
27510 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28 F,P,B) returns (
27520 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 B!=0)..**.** The
27530 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 sqlite3_uri_int
27540 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 64(F,P,D) routin
27550 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76 e converts the v
27560 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 alue of P into a
27570 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65 .** 64-bit signe
27580 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65 d integer and re
27590 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67 turns that integ
275a0 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f er, or D if P do
275b0 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e es not.** exist.
275c0 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f If the value o
275d0 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 f P is something
275e0 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69 other than an i
275f0 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 nteger, then.**
27600 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 zero is returned
27610 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 ..** .** If F is
27620 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c a NULL pointer,
27630 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 then sqlite3_ur
27640 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 i_parameter(F,P)
27650 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e returns NULL an
27660 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 d.** sqlite3_uri
27670 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 _boolean(F,P,B)
27680 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46 returns B. If F
27690 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 is not a NULL p
276a0 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 ointer and.** is
276b0 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 not a database
276c0 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f file pathname po
276d0 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74 inter that SQLit
276e0 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 e passed into th
276f0 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d e xOpen.** VFS m
27700 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 ethod, then the
27710 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 behavior of this
27720 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65 routine is unde
27730 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 fined and probab
27740 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c ly.** undesirabl
27750 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 e..*/.SQLITE_API
27760 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c const char *SQL
27770 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
27780 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 te3_uri_paramete
27790 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 r(const char *zF
277a0 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 ilename, const c
277b0 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 53 51 har *zParam);.SQ
277c0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
277d0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
277e0 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 te3_uri_boolean(
277f0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c const char *zFil
27800 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a e, const char *z
27810 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 Param, int bDefa
27820 75 6c 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ult);.SQLITE_API
27830 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 53 sqlite3_int64 S
27840 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
27850 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 lite3_uri_int64(
27860 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e const char*, con
27870 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 st char*, sqlite
27880 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 3_int64);.../*.*
27890 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f * CAPI3REF: Erro
278a0 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 r Codes And Mess
278b0 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 ages.** METHOD:
278c0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 sqlite3.**.** ^I
278d0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e f the most recen
278e0 74 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 t sqlite3_* API
278f0 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 20 call associated
27900 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61 with .** [databa
27910 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 se connection] D
27920 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 20 74 68 failed, then th
27930 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 e sqlite3_errcod
27940 65 28 44 29 20 69 6e 74 65 72 66 61 63 65 0a 2a e(D) interface.*
27950 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 * returns the nu
27960 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f meric [result co
27970 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 de] or [extended
27980 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f result code] fo
27990 72 20 74 68 61 74 0a 2a 2a 20 41 50 49 20 63 61 r that.** API ca
279a0 6c 6c 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6d 6f ll..** If the mo
279b0 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 st recent API ca
279c0 6c 6c 20 77 61 73 20 73 75 63 63 65 73 73 66 75 ll was successfu
279d0 6c 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 l,.** then the r
279e0 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d eturn value from
279f0 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 sqlite3_errcode
27a00 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e () is undefined.
27a10 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
27a20 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 _extended_errcod
27a30 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 e().** interface
27a40 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 is the same exc
27a50 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 ept that it alwa
27a60 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a ys returns the .
27a70 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 ** [extended res
27a80 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 ult code] even w
27a90 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 hen extended res
27aa0 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a ult codes are.**
27ab0 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a disabled..**.**
27ac0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 ^The sqlite3_er
27ad0 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 rmsg() and sqlit
27ae0 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 e3_errmsg16() re
27af0 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e turn English-lan
27b00 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 guage.** text th
27b10 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 at describes the
27b20 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 error, as eithe
27b30 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 r UTF-8 or UTF-1
27b40 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 6 respectively..
27b50 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 ** ^(Memory to h
27b60 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 old the error me
27b70 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 ssage string is
27b80 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c managed internal
27b90 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 ly..** The appli
27ba0 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 cation does not
27bb0 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 need to worry ab
27bc0 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 out freeing the
27bd0 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 result..** Howev
27be0 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 er, the error st
27bf0 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 ring might be ov
27c00 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 erwritten or dea
27c10 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 llocated by.** s
27c20 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 ubsequent calls
27c30 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 to other SQLite
27c40 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 interface functi
27c50 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ons.)^.**.** ^Th
27c60 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 e sqlite3_errstr
27c70 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 () interface ret
27c80 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68 urns the English
27c90 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a -language text.*
27ca0 2a 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 * that describes
27cb0 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 the [result cod
27cc0 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a e], as UTF-8..**
27cd0 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c ^(Memory to hol
27ce0 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 d the error mess
27cf0 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 age string is ma
27d00 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 naged internally
27d10 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 .** and must not
27d20 20 62 65 20 66 72 65 65 64 20 62 79 20 74 68 65 be freed by the
27d30 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a application)^..
27d40 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 **.** When the s
27d50 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 erialized [threa
27d60 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e ding mode] is in
27d70 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 use, it might b
27d80 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 e the.** case th
27d90 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f at a second erro
27da0 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 r occurs on a se
27db0 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e parate thread in
27dc0 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 between.** the
27dd0 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 time of the firs
27de0 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 t error and the
27df0 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e call to these in
27e00 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 terfaces..** Whe
27e10 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 n that happens,
27e20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 the second error
27e30 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 will be reporte
27e40 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a d since these.**
27e50 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 interfaces alwa
27e60 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f ys report the mo
27e70 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 st recent result
27e80 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 . To avoid.** t
27e90 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 his, each thread
27ea0 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c can obtain excl
27eb0 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 usive use of the
27ec0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
27ed0 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 ction] D.** by i
27ee0 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 nvoking [sqlite3
27ef0 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 _mutex_enter]([s
27f00 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d qlite3_db_mutex]
27f10 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 (D)) before begi
27f20 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 nning.** to use
27f30 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b D and invoking [
27f40 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 sqlite3_mutex_le
27f50 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 ave]([sqlite3_db
27f60 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 _mutex](D)) afte
27f70 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 r.** all calls t
27f80 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 o the interfaces
27f90 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65 listed here are
27fa0 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a completed..**.*
27fb0 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 * If an interfac
27fc0 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c e fails with SQL
27fd0 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 ITE_MISUSE, that
27fe0 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 means the inter
27ff0 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f face.** was invo
28000 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 ked incorrectly
28010 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 by the applicati
28020 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 on. In that cas
28030 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 e, the.** error
28040 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 code and message
28050 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 may or may not
28060 62 65 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 be set..*/.SQLIT
28070 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
28080 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
28090 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 _errcode(sqlite3
280a0 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 *db);.SQLITE_AP
280b0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
280c0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 78 74 CALL sqlite3_ext
280d0 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 ended_errcode(sq
280e0 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 lite3 *db);.SQLI
280f0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 TE_API const cha
28100 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c r *SQLITE_STDCAL
28110 4c 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 L sqlite3_errmsg
28120 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 (sqlite3*);.SQLI
28130 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 TE_API const voi
28140 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c d *SQLITE_STDCAL
28150 4c 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 L sqlite3_errmsg
28160 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 16(sqlite3*);.SQ
28170 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 LITE_API const c
28180 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 har *SQLITE_STDC
28190 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 72 72 73 ALL sqlite3_errs
281a0 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 tr(int);../*.**
281b0 43 41 50 49 33 52 45 46 3a 20 50 72 65 70 61 72 CAPI3REF: Prepar
281c0 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a ed Statement Obj
281d0 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a ect.** KEYWORDS:
281e0 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 {prepared state
281f0 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 ment} {prepared
28200 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a statements}.**.*
28210 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 * An instance of
28220 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 this object rep
28230 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 resents a single
28240 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 SQL statement t
28250 68 61 74 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20 hat.** has been
28260 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 62 69 compiled into bi
28270 6e 61 72 79 20 66 6f 72 6d 20 61 6e 64 20 69 73 nary form and is
28280 20 72 65 61 64 79 20 74 6f 20 62 65 20 65 76 61 ready to be eva
28290 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 luated..**.** Th
282a0 69 6e 6b 20 6f 66 20 65 61 63 68 20 53 51 4c 20 ink of each SQL
282b0 73 74 61 74 65 6d 65 6e 74 20 61 73 20 61 20 73 statement as a s
282c0 65 70 61 72 61 74 65 20 63 6f 6d 70 75 74 65 72 eparate computer
282d0 20 70 72 6f 67 72 61 6d 2e 20 20 54 68 65 0a 2a program. The.*
282e0 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 * original SQL t
282f0 65 78 74 20 69 73 20 73 6f 75 72 63 65 20 63 6f ext is source co
28300 64 65 2e 20 20 41 20 70 72 65 70 61 72 65 64 20 de. A prepared
28310 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 statement object
28320 20 0a 2a 2a 20 69 73 20 74 68 65 20 63 6f 6d 70 .** is the comp
28330 69 6c 65 64 20 6f 62 6a 65 63 74 20 63 6f 64 65 iled object code
28340 2e 20 20 41 6c 6c 20 53 51 4c 20 6d 75 73 74 20 . All SQL must
28350 62 65 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 be converted int
28360 6f 20 61 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 o a.** prepared
28370 73 74 61 74 65 6d 65 6e 74 20 62 65 66 6f 72 65 statement before
28380 20 69 74 20 63 61 6e 20 62 65 20 72 75 6e 2e 0a it can be run..
28390 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 2d 63 **.** The life-c
283a0 79 63 6c 65 20 6f 66 20 61 20 70 72 65 70 61 72 ycle of a prepar
283b0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a ed statement obj
283c0 65 63 74 20 75 73 75 61 6c 6c 79 20 67 6f 65 73 ect usually goes
283d0 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a like this:.**.*
283e0 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 * <ol>.** <li> C
283f0 72 65 61 74 65 20 74 68 65 20 70 72 65 70 61 72 reate the prepar
28400 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a ed statement obj
28410 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ect using [sqlit
28420 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
28430 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 ..** <li> Bind v
28440 61 6c 75 65 73 20 74 6f 20 5b 70 61 72 61 6d 65 alues to [parame
28450 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 ters] using the
28460 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 sqlite3_bind_*()
28470 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 .** interfa
28480 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e ces..** <li> Run
28490 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c the SQL by call
284a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 ing [sqlite3_ste
284b0 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 p()] one or more
284c0 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 times..** <li>
284d0 52 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 Reset the prepar
284e0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 ed statement usi
284f0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 ng [sqlite3_rese
28500 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 t()] then go bac
28510 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 k.** to ste
28520 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 p 2. Do this ze
28530 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 ro or more times
28540 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f ..** <li> Destro
28550 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 y the object usi
28560 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 ng [sqlite3_fina
28570 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c lize()]..** </ol
28580 3e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 >.*/.typedef str
28590 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 uct sqlite3_stmt
285a0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a sqlite3_stmt;..
285b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
285c0 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a Run-time Limits.
285d0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
285e0 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 e3.**.** ^(This
285f0 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 interface allows
28600 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 the size of var
28610 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 ious constructs
28620 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a to be limited.**
28630 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e on a connection
28640 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 by connection b
28650 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 asis. The first
28660 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
28670 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 e.** [database c
28680 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 onnection] whose
28690 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 limit is to be
286a0 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 set or queried.
286b0 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 The.** second p
286c0 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 arameter is one
286d0 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 of the [limit ca
286e0 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 tegories] that d
286f0 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 efine a.** class
28700 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 of constructs t
28710 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 o be size limite
28720 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61 d. The third pa
28730 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a rameter is the.*
28740 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 * new limit for
28750 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 that construct.)
28760 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ^.**.** ^If the
28770 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e new limit is a n
28780 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 egative number,
28790 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 the limit is unc
287a0 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 hanged..** ^(For
287b0 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65 each limit cate
287c0 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 gory SQLITE_LIMI
287d0 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 T_<i>NAME</i> th
287e0 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 ere is a .** [li
287f0 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 mits | hard uppe
28800 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 r bound].** set
28810 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 at compile-time
28820 62 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73 by a C preproces
28830 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 sor macro called
28840 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 .** [limits | SQ
28850 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 LITE_MAX_<i>NAME
28860 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 </i>]..** (The "
28870 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 _LIMIT_" in the
28880 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 name is changed
28890 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a to "_MAX_".))^.*
288a0 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 * ^Attempts to i
288b0 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 ncrease a limit
288c0 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 above its hard u
288d0 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a pper bound are.*
288e0 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 * silently trunc
288f0 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 ated to the hard
28900 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a upper bound..**
28910 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 .** ^Regardless
28920 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f of whether or no
28930 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 t the limit was
28940 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a changed, the .**
28950 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 [sqlite3_limit(
28960 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 )] interface ret
28970 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76 urns the prior v
28980 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 alue of the limi
28990 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f t..** ^Hence, to
289a0 20 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e find the curren
289b0 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d t value of a lim
289c0 69 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 it without chang
289d0 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c ing it,.** simpl
289e0 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e y invoke this in
289f0 74 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65 terface with the
28a00 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
28a10 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a set to -1..**.*
28a20 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 * Run-time limit
28a30 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 s are intended f
28a40 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 or use in applic
28a50 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 ations that mana
28a60 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 ge.** both their
28a70 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 own internal da
28a80 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 tabase and also
28a90 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61 databases that a
28aa0 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a re controlled.**
28ab0 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 by untrusted ex
28ac0 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 ternal sources.
28ad0 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c An example appl
28ae0 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 ication might be
28af0 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 a.** web browse
28b00 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f r that has its o
28b10 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 wn databases for
28b20 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 storing history
28b30 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 and.** separate
28b40 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 databases contr
28b50 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 olled by JavaScr
28b60 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 ipt applications
28b70 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f downloaded.** o
28b80 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e ff the Internet.
28b90 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 The internal d
28ba0 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 atabases can be
28bb0 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 given the.** lar
28bc0 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 ge, default limi
28bd0 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d ts. Databases m
28be0 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e anaged by extern
28bf0 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a al sources can.*
28c00 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 * be given much
28c10 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 smaller limits d
28c20 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 esigned to preve
28c30 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 nt a denial of s
28c40 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b ervice.** attack
28c50 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 . Developers mi
28c60 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f ght also want to
28c70 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 use the [sqlite
28c80 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 3_set_authorizer
28c90 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 ()].** interface
28ca0 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 to further cont
28cb0 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 rol untrusted SQ
28cc0 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 L. The size of
28cd0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 the database.**
28ce0 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e created by an un
28cf0 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63 trusted script c
28d00 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 an be contained
28d10 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 using the.** [ma
28d20 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 x_page_count] [P
28d30 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 RAGMA]..**.** Ne
28d40 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 w run-time limit
28d50 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 categories may
28d60 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 be added in futu
28d70 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a re releases..*/.
28d80 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
28d90 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
28da0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 lite3_limit(sqli
28db0 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e te3*, int id, in
28dc0 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a t newVal);../*.*
28dd0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d * CAPI3REF: Run-
28de0 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 Time Limit Categ
28df0 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 ories.** KEYWORD
28e00 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f S: {limit catego
28e10 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 ry} {*limit cate
28e20 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 gories}.**.** Th
28e30 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 ese constants de
28e40 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 fine various per
28e50 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a formance limits.
28e60 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c ** that can be l
28e70 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 owered at run-ti
28e80 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 me using [sqlite
28e90 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 3_limit()]..** T
28ea0 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 he synopsis of t
28eb0 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 he meanings of t
28ec0 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 he various limit
28ed0 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 s is shown below
28ee0 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 ..** Additional
28ef0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 information is a
28f00 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d vailable at [lim
28f10 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 its | Limits in
28f20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c SQLite]..**.** <
28f30 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f dl>.** [[SQLITE_
28f40 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e LIMIT_LENGTH]] ^
28f50 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
28f60 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a T_LENGTH</dt>.**
28f70 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
28f80 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 size of any str
28f90 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 ing or BLOB or t
28fa0 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 able row, in byt
28fb0 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 es.<dd>)^.**.**
28fc0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 [[SQLITE_LIMIT_S
28fd0 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 QL_LENGTH]] ^(<d
28fe0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 t>SQLITE_LIMIT_S
28ff0 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a QL_LENGTH</dt>.*
29000 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
29010 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 m length of an S
29020 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e QL statement, in
29030 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a bytes.</dd>)^.*
29040 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 *.** [[SQLITE_LI
29050 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c MIT_COLUMN]] ^(<
29060 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
29070 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c COLUMN</dt>.** <
29080 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e dd>The maximum n
29090 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
290a0 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 in a table defi
290b0 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 nition or in the
290c0 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f .** result set o
290d0 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 f a [SELECT] or
290e0 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 the maximum numb
290f0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e er of columns in
29100 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 an index.** or
29110 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f in an ORDER BY o
29120 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 r GROUP BY claus
29130 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 e.</dd>)^.**.**
29140 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 [[SQLITE_LIMIT_E
29150 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 XPR_DEPTH]] ^(<d
29160 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 t>SQLITE_LIMIT_E
29170 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a XPR_DEPTH</dt>.*
29180 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
29190 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 m depth of the p
291a0 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 arse tree on any
291b0 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 expression.</dd
291c0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 >)^.**.** [[SQLI
291d0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e TE_LIMIT_COMPOUN
291e0 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 D_SELECT]] ^(<dt
291f0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f >SQLITE_LIMIT_CO
29200 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 MPOUND_SELECT</d
29210 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
29220 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
29230 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f terms in a compo
29240 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 und SELECT state
29250 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a ment.</dd>)^.**.
29260 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ** [[SQLITE_LIMI
29270 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 T_VDBE_OP]] ^(<d
29280 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 t>SQLITE_LIMIT_V
29290 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c DBE_OP</dt>.** <
292a0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e dd>The maximum n
292b0 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 umber of instruc
292c0 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 tions in a virtu
292d0 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 al machine progr
292e0 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d am.** used to im
292f0 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 plement an SQL s
29300 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 tatement. This
29310 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72 limit is not cur
29320 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 rently.** enforc
29330 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20 ed, though that
29340 6d 69 67 68 74 20 62 65 20 61 64 64 65 64 20 69 might be added i
29350 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 n some future re
29360 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 lease of.** SQLi
29370 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a te.</dd>)^.**.**
29380 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f [[SQLITE_LIMIT_
29390 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e FUNCTION_ARG]] ^
293a0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
293b0 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f T_FUNCTION_ARG</
293c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
293d0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
293e0 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 arguments on a
293f0 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e function.</dd>)^
29400 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
29410 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d LIMIT_ATTACHED]]
29420 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
29430 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 MIT_ATTACHED</dt
29440 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
29450 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b imum number of [
29460 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 ATTACH | attache
29470 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c d databases].)^<
29480 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
29490 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 ITE_LIMIT_LIKE_P
294a0 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a ATTERN_LENGTH]].
294b0 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f ** ^(<dt>SQLITE_
294c0 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 LIMIT_LIKE_PATTE
294d0 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a RN_LENGTH</dt>.*
294e0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
294f0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 m length of the
29500 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 pattern argument
29510 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f to the [LIKE] o
29520 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 r.** [GLOB] oper
29530 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a ators.</dd>)^.**
29540 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d .** [[SQLITE_LIM
29550 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 IT_VARIABLE_NUMB
29560 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 ER]].** ^(<dt>SQ
29570 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 LITE_LIMIT_VARIA
29580 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a BLE_NUMBER</dt>.
29590 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
295a0 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 um index number
295b0 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 of any [paramete
295c0 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 r] in an SQL sta
295d0 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 tement.)^.**.**
295e0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 [[SQLITE_LIMIT_T
295f0 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e RIGGER_DEPTH]] ^
29600 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
29610 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c T_TRIGGER_DEPTH<
29620 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
29630 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 maximum depth of
29640 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 recursion for t
29650 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a riggers.</dd>)^.
29660 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c **.** [[SQLITE_L
29670 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 IMIT_WORKER_THRE
29680 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 ADS]] ^(<dt>SQLI
29690 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f TE_LIMIT_WORKER_
296a0 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 THREADS</dt>.**
296b0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
296c0 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 69 6c 69 number of auxili
296d0 61 72 79 20 77 6f 72 6b 65 72 20 74 68 72 65 61 ary worker threa
296e0 64 73 20 74 68 61 74 20 61 20 73 69 6e 67 6c 65 ds that a single
296f0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 .** [prepared st
29700 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61 atement] may sta
29710 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f rt.</dd>)^.** </
29720 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 dl>.*/.#define S
29730 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 QLITE_LIMIT_LENG
29740 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 TH
29750 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 0.#define
29760 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c SQLITE_LIMIT_SQL
29770 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 _LENGTH
29780 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 1.#define
29790 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f SQLITE_LIMIT_CO
297a0 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 LUMN
297b0 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 2.#defin
297c0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 e SQLITE_LIMIT_E
297d0 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 XPR_DEPTH
297e0 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 3.#defi
297f0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
29800 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 COMPOUND_SELECT
29810 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 4.#def
29820 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
29830 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 _VDBE_OP
29840 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 5.#de
29850 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
29860 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 T_FUNCTION_ARG
29870 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 6.#d
29880 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
29890 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 IT_ATTACHED
298a0 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 7.#
298b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
298c0 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e MIT_LIKE_PATTERN
298d0 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a _LENGTH 8.
298e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
298f0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 IMIT_VARIABLE_NU
29900 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39 MBER 9
29910 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
29920 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 LIMIT_TRIGGER_DE
29930 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31 PTH 1
29940 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
29950 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 _LIMIT_WORKER_TH
29960 52 45 41 44 53 20 20 20 20 20 20 20 20 20 20 20 READS
29970 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 11../*.** CAPI3R
29980 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e EF: Compiling An
29990 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a SQL Statement.*
299a0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c * KEYWORDS: {SQL
299b0 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 statement compi
299c0 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 ler}.** METHOD:
299d0 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 sqlite3.** CONST
299e0 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f RUCTOR: sqlite3_
299f0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 stmt.**.** To ex
29a00 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 ecute an SQL que
29a10 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 ry, it must firs
29a20 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e t be compiled in
29a30 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a to a byte-code.*
29a40 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 * program using
29a50 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 one of these rou
29a60 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 tines..**.** The
29a70 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c first argument,
29a80 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 "db", is a [dat
29a90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
29aa0 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 ] obtained from
29ab0 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 a.** prior succe
29ac0 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 ssful call to [s
29ad0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 qlite3_open()],
29ae0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 [sqlite3_open_v2
29af0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 ()] or.** [sqlit
29b00 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 e3_open16()]. T
29b10 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
29b20 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 ection must not
29b30 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 have been closed
29b40 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f ..**.** The seco
29b50 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 nd argument, "zS
29b60 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 ql", is the stat
29b70 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 ement to be comp
29b80 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a iled, encoded.**
29b90 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 as either UTF-8
29ba0 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 or UTF-16. The
29bb0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
29bc0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 () and sqlite3_p
29bd0 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 repare_v2().** i
29be0 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54 nterfaces use UT
29bf0 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 F-8, and sqlite3
29c00 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 _prepare16() and
29c10 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
29c20 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 16_v2().** use U
29c30 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 TF-16..**.** ^If
29c40 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d the nByte argum
29c50 65 6e 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c ent is negative,
29c60 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 then zSql is re
29c70 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 ad up to the.**
29c80 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 first zero termi
29c90 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 nator. ^If nByte
29ca0 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74 68 is positive, th
29cb0 65 6e 20 69 74 20 69 73 20 74 68 65 0a 2a 2a 20 en it is the.**
29cc0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
29cd0 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 read from zSql.
29ce0 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 7a 65 ^If nByte is ze
29cf0 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 72 65 70 ro, then no prep
29d00 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e ared.** statemen
29d10 74 20 69 73 20 67 65 6e 65 72 61 74 65 64 2e 0a t is generated..
29d20 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 ** If the caller
29d30 20 6b 6e 6f 77 73 20 74 68 61 74 20 74 68 65 20 knows that the
29d40 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 supplied string
29d50 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 is nul-terminate
29d60 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 72 65 d, then.** there
29d70 20 69 73 20 61 20 73 6d 61 6c 6c 20 70 65 72 66 is a small perf
29d80 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 ormance advantag
29d90 65 20 74 6f 20 70 61 73 73 69 6e 67 20 61 6e 20 e to passing an
29da0 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 nByte parameter
29db0 74 68 61 74 0a 2a 2a 20 69 73 20 74 68 65 20 6e that.** is the n
29dc0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 umber of bytes i
29dd0 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 n the input stri
29de0 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c ng <i>including<
29df0 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 /i>.** the nul-t
29e00 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a erminator..**.**
29e10 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e ^If pzTail is n
29e20 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a ot NULL then *pz
29e30 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 Tail is made to
29e40 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 point to the fir
29e50 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 st byte.** past
29e60 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 the end of the f
29e70 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 irst SQL stateme
29e80 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 nt in zSql. The
29e90 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 se routines only
29ea0 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 .** compile the
29eb0 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 first statement
29ec0 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 in zSql, so *pzT
29ed0 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e ail is left poin
29ee0 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 ting to.** what
29ef0 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c remains uncompil
29f00 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 ed..**.** ^*ppSt
29f10 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 mt is left point
29f20 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 ing to a compile
29f30 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 d [prepared stat
29f40 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 ement] that can
29f50 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 be.** executed u
29f60 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 sing [sqlite3_st
29f70 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 ep()]. ^If ther
29f80 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a e is an error, *
29f90 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a ppStmt is set.**
29fa0 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 to NULL. ^If t
29fb0 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f he input text co
29fc0 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 ntains no SQL (i
29fd0 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 f the input is a
29fe0 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e n empty.** strin
29ff0 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 g or a comment)
2a000 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 then *ppStmt is
2a010 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 set to NULL..**
2a020 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 The calling proc
2a030 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 edure is respons
2a040 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e ible for deletin
2a050 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a g the compiled.*
2a060 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 * SQL statement
2a070 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 using [sqlite3_f
2a080 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 inalize()] after
2a090 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 it has finished
2a0a0 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 with it..** ppS
2a0b0 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e tmt may not be N
2a0c0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 ULL..**.** ^On s
2a0d0 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 uccess, the sqli
2a0e0 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 te3_prepare() fa
2a0f0 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 mily of routines
2a100 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
2a110 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 OK];.** otherwis
2a120 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 e an [error code
2a130 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a ] is returned..*
2a140 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
2a150 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e _prepare_v2() an
2a160 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 d sqlite3_prepar
2a170 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 e16_v2() interfa
2a180 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d ces are.** recom
2a190 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e mended for all n
2a1a0 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 ew programs. The
2a1b0 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 two older inter
2a1c0 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e faces are retain
2a1d0 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 ed.** for backwa
2a1e0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 rds compatibilit
2a1f0 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65 y, but their use
2a200 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e is discouraged.
2a210 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22 .** ^In the "v2"
2a220 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 interfaces, the
2a230 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
2a240 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 ent.** that is r
2a250 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 eturned (the [sq
2a260 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 lite3_stmt] obje
2a270 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 ct) contains a c
2a280 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 opy of the.** or
2a290 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e iginal SQL text.
2a2a0 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65 This causes the
2a2b0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
2a2c0 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a ] interface to.*
2a2d0 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65 * behave differe
2a2e0 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 ntly in three wa
2a2f0 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a ys:.**.** <ol>.*
2a300 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 * <li>.** ^If th
2a310 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d e database schem
2a320 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 a changes, inste
2a330 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 ad of returning
2a340 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 [SQLITE_SCHEMA]
2a350 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 as it.** always
2a360 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c used to do, [sql
2a370 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c ite3_step()] wil
2a380 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 l automatically
2a390 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 recompile the SQ
2a3a0 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 L.** statement a
2a3b0 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 nd try to run it
2a3c0 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 again. As many
2a3d0 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 as [SQLITE_MAX_S
2a3e0 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 CHEMA_RETRY].**
2a3f0 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 retries will occ
2a400 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 ur before sqlite
2a410 33 5f 73 74 65 70 28 29 20 67 69 76 65 73 20 75 3_step() gives u
2a420 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e p and returns an
2a430 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e error..** </li>
2a440 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e .**.** <li>.** ^
2a450 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 When an error oc
2a460 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 curs, [sqlite3_s
2a470 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 tep()] will retu
2a480 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 rn one of the de
2a490 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 tailed.** [error
2a4a0 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 codes] or [exte
2a4b0 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 nded error codes
2a4c0 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 ]. ^The legacy
2a4d0 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 behavior was tha
2a4e0 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 t.** [sqlite3_st
2a4f0 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 ep()] would only
2a500 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 return a generi
2a510 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d c [SQLITE_ERROR]
2a520 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 result code.**
2a530 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 and the applicat
2a540 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 ion would have t
2a550 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 o make a second
2a560 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
2a570 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 _reset()].** in
2a580 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 order to find th
2a590 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 e underlying cau
2a5a0 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 se of the proble
2a5b0 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22 m. With the "v2"
2a5c0 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 prepare.** inte
2a5d0 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 rfaces, the unde
2a5e0 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f rlying reason fo
2a5f0 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 r the error is r
2a600 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 eturned immediat
2a610 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a ely..** </li>.**
2a620 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 .** <li>.** ^If
2a630 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c the specific val
2a640 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 ue bound to [par
2a650 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 ameter | host pa
2a660 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 rameter] in the
2a670 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 .** WHERE clause
2a680 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 might influence
2a690 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 the choice of q
2a6a0 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 uery plan for a
2a6b0 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 statement,.** th
2a6c0 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 en the statement
2a6d0 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 will be automat
2a6e0 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 ically recompile
2a6f0 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 68 d, as if there h
2a700 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 ad been .** a sc
2a710 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 hema change, on
2a720 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 the first [sqli
2a730 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c te3_step()] call
2a740 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 following any c
2a750 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 hange.** to the
2a760 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 [sqlite3_bind_te
2a770 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f xt | bindings] o
2a780 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 f that [paramete
2a790 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 r]. .** ^The spe
2a7a0 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 cific value of W
2a7b0 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 HERE-clause [par
2a7c0 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e ameter] might in
2a7d0 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 fluence the .**
2a7e0 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 choice of query
2a7f0 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 plan if the para
2a800 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 meter is the lef
2a810 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 t-hand side of a
2a820 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 [LIKE].** or [G
2a830 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 LOB] operator or
2a840 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 if the paramete
2a850 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f r is compared to
2a860 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 an indexed colu
2a870 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 mn.** and the [S
2a880 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 QLITE_ENABLE_STA
2a890 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 T3] compile-time
2a8a0 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c option is enabl
2a8b0 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 ed..** </li>.**
2a8c0 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f </ol>.*/.SQLITE_
2a8d0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 API int SQLITE_S
2a8e0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70 TDCALL sqlite3_p
2a8f0 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 repare(. sqlite
2a900 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
2a910 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 /* Database ha
2a920 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
2a930 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 char *zSql,
2a940 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 /* SQL stateme
2a950 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 nt, UTF-8 encode
2a960 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 d */. int nByte
2a970 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f , /
2a980 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 * Maximum length
2a990 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 of zSql in byte
2a9a0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f s. */. sqlite3_
2a9b0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 stmt **ppStmt,
2a9c0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e /* OUT: Statemen
2a9d0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f t handle */. co
2a9e0 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 nst char **pzTai
2a9f0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f l /* OUT: Po
2aa00 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 inter to unused
2aa10 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 portion of zSql
2aa20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 */.);.SQLITE_API
2aa30 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
2aa40 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 ALL sqlite3_prep
2aa50 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 are_v2(. sqlite
2aa60 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
2aa70 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 /* Database ha
2aa80 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
2aa90 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 char *zSql,
2aaa0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 /* SQL stateme
2aab0 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 nt, UTF-8 encode
2aac0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 d */. int nByte
2aad0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f , /
2aae0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 * Maximum length
2aaf0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 of zSql in byte
2ab00 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f s. */. sqlite3_
2ab10 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 stmt **ppStmt,
2ab20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e /* OUT: Statemen
2ab30 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f t handle */. co
2ab40 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 nst char **pzTai
2ab50 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f l /* OUT: Po
2ab60 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 inter to unused
2ab70 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 portion of zSql
2ab80 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 */.);.SQLITE_API
2ab90 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
2aba0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 ALL sqlite3_prep
2abb0 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 are16(. sqlite3
2abc0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 *db,
2abd0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e /* Database han
2abe0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 dle */. const v
2abf0 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 oid *zSql,
2ac00 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e /* SQL statemen
2ac10 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 t, UTF-16 encode
2ac20 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 d */. int nByte
2ac30 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f , /
2ac40 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 * Maximum length
2ac50 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 of zSql in byte
2ac60 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f s. */. sqlite3_
2ac70 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 stmt **ppStmt,
2ac80 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e /* OUT: Statemen
2ac90 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f t handle */. co
2aca0 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 nst void **pzTai
2acb0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f l /* OUT: Po
2acc0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 inter to unused
2acd0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 portion of zSql
2ace0 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 */.);.SQLITE_API
2acf0 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
2ad00 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 ALL sqlite3_prep
2ad10 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 are16_v2(. sqli
2ad20 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
2ad30 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 /* Database
2ad40 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
2ad50 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 t void *zSql,
2ad60 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 /* SQL state
2ad70 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 ment, UTF-16 enc
2ad80 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 oded */. int nB
2ad90 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 yte,
2ada0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e /* Maximum len
2adb0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 gth of zSql in b
2adc0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 ytes. */. sqlit
2add0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 e3_stmt **ppStmt
2ade0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 , /* OUT: State
2adf0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 ment handle */.
2ae00 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a const void **pz
2ae10 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a Tail /* OUT:
2ae20 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 Pointer to unus
2ae30 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 ed portion of zS
2ae40 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 ql */.);../*.**
2ae50 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 CAPI3REF: Retrie
2ae60 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 ving Statement S
2ae70 51 4c 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 QL.** METHOD: sq
2ae80 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a lite3_stmt.**.**
2ae90 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 ^This interface
2aea0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
2aeb0 72 65 74 72 69 65 76 65 20 61 20 73 61 76 65 64 retrieve a saved
2aec0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 copy of the ori
2aed0 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 ginal.** SQL tex
2aee0 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 t used to create
2aef0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
2af00 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 tement] if that
2af10 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a statement was.**
2af20 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 compiled using
2af30 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f either [sqlite3_
2af40 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 prepare_v2()] or
2af50 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2af60 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 e16_v2()]..*/.SQ
2af70 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 LITE_API const c
2af80 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 har *SQLITE_STDC
2af90 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 ALL sqlite3_sql(
2afa0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 sqlite3_stmt *pS
2afb0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 tmt);../*.** CAP
2afc0 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 I3REF: Determine
2afd0 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 If An SQL State
2afe0 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 ment Writes The
2aff0 44 61 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48 Database.** METH
2b000 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 OD: sqlite3_stmt
2b010 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
2b020 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c te3_stmt_readonl
2b030 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 y(X) interface r
2b040 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e eturns true (non
2b050 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 -zero) if.** and
2b060 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 only if the [pr
2b070 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2b080 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 ] X makes no dir
2b090 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a ect changes to.*
2b0a0 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 * the content of
2b0b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
2b0c0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 le..**.** Note t
2b0d0 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e hat [application
2b0e0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e -defined SQL fun
2b0f0 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 ctions] or.** [v
2b100 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d irtual tables] m
2b110 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 ight change the
2b120 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 database indirec
2b130 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66 tly as a side ef
2b140 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 fect. .** ^(For
2b150 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 example, if an
2b160 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 application defi
2b170 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 nes a function "
2b180 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a eval()" that .**
2b190 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f calls [sqlite3_
2b1a0 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 exec()], then th
2b1b0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 e following SQL
2b1c0 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a statement would.
2b1d0 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 ** change the da
2b1e0 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f tabase file thro
2b1f0 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 ugh side-effects
2b200 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 :.**.** <blockqu
2b210 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 ote><pre>.**
2b220 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c SELECT eval('DEL
2b230 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 ETE FROM t1') FR
2b240 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e OM t2;.** </pre>
2b250 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a </blockquote>.**
2b260 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 .** But because
2b270 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 the [SELECT] sta
2b280 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 tement does not
2b290 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 change the datab
2b2a0 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 ase file.** dire
2b2b0 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 ctly, sqlite3_st
2b2c0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f mt_readonly() wo
2b2d0 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e uld still return
2b2e0 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e true.)^.**.** ^
2b2f0 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 Transaction cont
2b300 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 rol statements s
2b310 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 uch as [BEGIN],
2b320 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 [COMMIT], [ROLLB
2b330 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f ACK],.** [SAVEPO
2b340 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 INT], and [RELEA
2b350 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 SE] cause sqlite
2b360 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 3_stmt_readonly(
2b370 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 ) to return true
2b380 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 ,.** since the s
2b390 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 tatements themse
2b3a0 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 lves do not actu
2b3b0 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 ally modify the
2b3c0 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 database but.**
2b3d0 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 rather they cont
2b3e0 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f rol the timing o
2b3f0 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 f when other sta
2b400 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 tements modify t
2b410 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e he .** database.
2b420 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 ^The [ATTACH]
2b430 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 and [DETACH] sta
2b440 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 tements also cau
2b450 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 se.** sqlite3_st
2b460 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f mt_readonly() to
2b470 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e return true sin
2b480 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 ce, while those
2b490 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 statements.** ch
2b4a0 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 ange the configu
2b4b0 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 ration of a data
2b4c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c base connection,
2b4d0 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b they do not mak
2b4e0 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f e .** changes to
2b4f0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 the content of
2b500 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
2b510 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 53 es on disk..*/.S
2b520 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 QLITE_API int SQ
2b530 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
2b540 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e ite3_stmt_readon
2b550 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 ly(sqlite3_stmt
2b560 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 *pStmt);../*.**
2b570 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d CAPI3REF: Determ
2b580 69 6e 65 20 49 66 20 41 20 50 72 65 70 61 72 65 ine If A Prepare
2b590 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20 d Statement Has
2b5a0 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 20 4d 45 Been Reset.** ME
2b5b0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 THOD: sqlite3_st
2b5c0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 mt.**.** ^The sq
2b5d0 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 lite3_stmt_busy(
2b5e0 53 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 S) interface ret
2b5f0 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a urns true (non-z
2b600 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b ero) if the.** [
2b610 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2b620 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 nt] S has been s
2b630 74 65 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 tepped at least
2b640 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b once using .** [
2b650 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d sqlite3_step(S)]
2b660 20 62 75 74 20 68 61 73 20 6e 65 69 74 68 65 72 but has neither
2b670 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 run to completi
2b680 6f 6e 20 28 72 65 74 75 72 6e 65 64 0a 2a 2a 20 on (returned.**
2b690 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 66 72 [SQLITE_DONE] fr
2b6a0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 om [sqlite3_step
2b6b0 28 53 29 5d 29 20 6e 6f 72 0a 2a 2a 20 62 65 65 (S)]) nor.** bee
2b6c0 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73 n reset using [s
2b6d0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d qlite3_reset(S)]
2b6e0 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f . ^The sqlite3_
2b6f0 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 stmt_busy(S).**
2b700 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
2b710 73 20 66 61 6c 73 65 20 69 66 20 53 20 69 73 20 s false if S is
2b720 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 a NULL pointer.
2b730 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a If S is not a .
2b740 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 ** NULL pointer
2b750 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 and is not a poi
2b760 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20 nter to a valid
2b770 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2b780 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 ent].** object,
2b790 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f then the behavio
2b7a0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 r is undefined a
2b7b0 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 nd probably unde
2b7c0 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 sirable..**.** T
2b7d0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 his interface ca
2b7e0 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d n be used in com
2b7f0 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 bination [sqlite
2b800 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 3_next_stmt()].*
2b810 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 * to locate all
2b820 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2b830 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 nts associated w
2b840 69 74 68 20 61 20 64 61 74 61 62 61 73 65 20 0a ith a database .
2b850 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 ** connection th
2b860 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f at are in need o
2b870 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20 f being reset.
2b880 54 68 69 73 20 63 61 6e 20 62 65 20 75 73 65 64 This can be used
2b890 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 ,.** for example
2b8a0 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 , in diagnostic
2b8b0 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72 routines to sear
2b8c0 63 68 20 66 6f 72 20 70 72 65 70 61 72 65 64 20 ch for prepared
2b8d0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74 .** statements t
2b8e0 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 hat are holding
2b8f0 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 a transaction op
2b900 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 en..*/.SQLITE_AP
2b910 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
2b920 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 74 6d CALL sqlite3_stm
2b930 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 t_busy(sqlite3_s
2b940 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 tmt*);../*.** CA
2b950 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 PI3REF: Dynamica
2b960 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 lly Typed Value
2b970 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 Object.** KEYWOR
2b980 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 DS: {protected s
2b990 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 qlite3_value} {u
2b9a0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
2b9b0 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 e3_value}.**.**
2b9c0 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 SQLite uses the
2b9d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
2b9e0 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e ject to represen
2b9f0 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 t all values.**
2ba00 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 that can be stor
2ba10 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 ed in a database
2ba20 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 table. SQLite u
2ba30 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 ses dynamic typi
2ba40 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 ng.** for the va
2ba50 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 lues it stores.
2ba60 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 ^Values stored
2ba70 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 in sqlite3_value
2ba80 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 objects.** can
2ba90 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f be integers, flo
2baa0 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 ating point valu
2bab0 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f es, strings, BLO
2bac0 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a Bs, or NULL..**.
2bad0 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 ** An sqlite3_va
2bae0 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 lue object may b
2baf0 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 e either "protec
2bb00 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 ted" or "unprote
2bb10 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 cted"..** Some i
2bb20 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 nterfaces requir
2bb30 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 e a protected sq
2bb40 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 lite3_value. Ot
2bb50 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a her interfaces.*
2bb60 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 * will accept ei
2bb70 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 ther a protected
2bb80 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 or an unprotect
2bb90 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
2bba0 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 ..** Every inter
2bbb0 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74 face that accept
2bbc0 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 s sqlite3_value
2bbd0 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 arguments specif
2bbe0 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f ies.** whether o
2bbf0 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 r not it require
2bc00 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 s a protected sq
2bc10 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 54 68 lite3_value. Th
2bc20 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 e.** [sqlite3_va
2bc30 6c 75 65 5f 64 75 70 28 29 5d 20 69 6e 74 65 72 lue_dup()] inter
2bc40 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 face can be used
2bc50 20 74 6f 20 63 6f 6e 73 74 72 75 63 74 20 61 20 to construct a
2bc60 6e 65 77 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65 new .** protecte
2bc70 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 d sqlite3_value
2bc80 66 72 6f 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63 from an unprotec
2bc90 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
2bca0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 e..**.** The ter
2bcb0 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 ms "protected" a
2bcc0 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 nd "unprotected"
2bcd0 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 refer to whethe
2bce0 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 r or not.** a mu
2bcf0 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e tex is held. An
2bd00 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 internal mutex
2bd10 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 is held for a pr
2bd20 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 otected.** sqlit
2bd30 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 e3_value object
2bd40 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 but no mutex is
2bd50 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 held for an unpr
2bd60 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 otected.** sqlit
2bd70 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e e3_value object.
2bd80 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 If SQLite is c
2bd90 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 ompiled to be si
2bda0 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a ngle-threaded.**
2bdb0 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 (with [SQLITE_T
2bdc0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 HREADSAFE=0] and
2bdd0 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 with [sqlite3_t
2bde0 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 hreadsafe()] ret
2bdf0 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 urning 0).** or
2be00 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e if SQLite is run
2be10 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 in one of reduc
2be20 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a ed mutex modes .
2be30 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ** [SQLITE_CONFI
2be40 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 G_SINGLETHREAD]
2be50 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 or [SQLITE_CONFI
2be60 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a G_MULTITHREAD].*
2be70 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 * then there is
2be80 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 no distinction b
2be90 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 etween protected
2bea0 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 and unprotected
2beb0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 .** sqlite3_valu
2bec0 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 e objects and th
2bed0 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 ey can be used i
2bee0 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 nterchangeably.
2bef0 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 However,.** for
2bf00 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f maximum code po
2bf10 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 rtability it is
2bf20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 recommended that
2bf30 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a applications.**
2bf40 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 still make the
2bf50 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 distinction betw
2bf60 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e een protected an
2bf70 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a d unprotected.**
2bf80 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
2bf90 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e bjects even when
2bfa0 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 not strictly re
2bfb0 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 quired..**.** ^T
2bfc0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 he sqlite3_value
2bfd0 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 objects that ar
2bfe0 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61 e passed as para
2bff0 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a meters into the.
2c000 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
2c010 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f n of [applicatio
2c020 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 n-defined SQL fu
2c030 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f nctions] are pro
2c040 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 tected..** ^The
2c050 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
2c060 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 ject returned by
2c070 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c .** [sqlite3_col
2c080 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 umn_value()] is
2c090 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 unprotected..**
2c0a0 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 Unprotected sqli
2c0b0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
2c0c0 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 s may only be us
2c0d0 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 ed with.** [sqli
2c0e0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 te3_result_value
2c0f0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
2c100 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a _bind_value()]..
2c110 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f ** The [sqlite3_
2c120 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c value_blob | sql
2c130 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 ite3_value_type(
2c140 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 )] family of.**
2c150 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 interfaces requi
2c160 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c re protected sql
2c170 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
2c180 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 ts..*/.typedef s
2c190 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 truct Mem sqlite
2c1a0 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 3_value;../*.**
2c1b0 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 CAPI3REF: SQL Fu
2c1c0 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f nction Context O
2c1d0 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 bject.**.** The
2c1e0 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 context in which
2c1f0 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e an SQL function
2c200 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f executes is sto
2c210 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c red in an.** sql
2c220 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a ite3_context obj
2c230 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 ect. ^A pointer
2c240 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 to an sqlite3_c
2c250 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a ontext object.**
2c260 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 is always first
2c270 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 parameter to [a
2c280 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
2c290 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 ed SQL functions
2c2a0 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 ]..** The applic
2c2b0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 ation-defined SQ
2c2c0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 L function imple
2c2d0 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 mentation will p
2c2e0 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e ass this.** poin
2c2f0 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f ter through into
2c300 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 calls to [sqlit
2c310 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 e3_result_int |
2c320 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 sqlite3_result()
2c330 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 ],.** [sqlite3_a
2c340 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
2c350 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 ()], [sqlite3_us
2c360 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b er_data()],.** [
2c370 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f sqlite3_context_
2c380 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 db_handle()], [s
2c390 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 qlite3_get_auxda
2c3a0 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 ta()],.** and/or
2c3b0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 [sqlite3_set_au
2c3c0 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 xdata()]..*/.typ
2c3d0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
2c3e0 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 te3_context sqli
2c3f0 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a te3_context;../*
2c400 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 .** CAPI3REF: Bi
2c410 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 nding Values To
2c420 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 Prepared Stateme
2c430 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a nts.** KEYWORDS:
2c440 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 {host parameter
2c450 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 } {host paramete
2c460 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 rs} {host parame
2c470 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 ter name}.** KEY
2c480 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 WORDS: {SQL para
2c490 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 meter} {SQL para
2c4a0 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 meters} {paramet
2c4b0 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d er binding}.** M
2c4c0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 ETHOD: sqlite3_s
2c4d0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 tmt.**.** ^(In t
2c4e0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
2c4f0 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b text input to [
2c500 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
2c510 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 v2()] and its va
2c520 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 riants,.** liter
2c530 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 als may be repla
2c540 63 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 ced by a [parame
2c550 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 ter] that matche
2c560 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 s one of followi
2c570 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a ng.** templates:
2c580 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c .**.** <ul>.** <
2c590 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 li> ?.** <li>
2c5a0 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 ?NNN.** <li> :V
2c5b0 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 VV.** <li> @VVV
2c5c0 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a .** <li> $VVV.*
2c5d0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e * </ul>.**.** In
2c5e0 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 the templates a
2c5f0 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 bove, NNN repres
2c600 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 ents an integer
2c610 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 literal,.** and
2c620 56 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 VVV represents a
2c630 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 n alphanumeric i
2c640 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 dentifier.)^ ^T
2c650 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 he values of the
2c660 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 se.** parameters
2c670 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 (also called "h
2c680 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 ost parameter na
2c690 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 mes" or "SQL par
2c6a0 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e ameters").** can
2c6b0 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 be set using th
2c6c0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a e sqlite3_bind_*
2c6d0 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 () routines defi
2c6e0 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 ned here..**.**
2c6f0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d ^The first argum
2c700 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ent to the sqlit
2c710 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 e3_bind_*() rout
2c720 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a ines is always.*
2c730 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 * a pointer to t
2c740 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 he [sqlite3_stmt
2c750 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 ] object returne
2c760 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 d from.** [sqlit
2c770 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
2c780 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 or its variants
2c790 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 ..**.** ^The sec
2c7a0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ond argument is
2c7b0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 the index of the
2c7c0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 SQL parameter t
2c7d0 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 o be set..** ^Th
2c7e0 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 e leftmost SQL p
2c7f0 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 arameter has an
2c800 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 index of 1. ^Wh
2c810 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 en the same name
2c820 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 d.** SQL paramet
2c830 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 er is used more
2c840 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e than once, secon
2c850 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 d and subsequent
2c860 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 .** occurrences
2c870 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e have the same in
2c880 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74 dex as the first
2c890 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 occurrence..**
2c8a0 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e ^The index for n
2c8b0 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 amed parameters
2c8c0 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 can be looked up
2c8d0 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 using the.** [s
2c8e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
2c8f0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 meter_index()] A
2c900 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 PI if desired.
2c910 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f ^The index.** fo
2c920 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 r "?NNN" paramet
2c930 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 ers is the value
2c940 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 of NNN..** ^The
2c950 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 NNN value must
2c960 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 be between 1 and
2c970 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 the [sqlite3_li
2c980 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 mit()].** parame
2c990 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ter [SQLITE_LIMI
2c9a0 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 T_VARIABLE_NUMBE
2c9b0 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 R] (default valu
2c9c0 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e e: 999)..**.** ^
2c9d0 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 The third argume
2c9e0 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 nt is the value
2c9f0 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 to bind to the p
2ca00 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 arameter..** ^If
2ca10 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d the third param
2ca20 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
2ca30 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 bind_text() or s
2ca40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
2ca50 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 16().** or sqlit
2ca60 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 e3_bind_blob() i
2ca70 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
2ca80 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 then the fourth
2ca90 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 parameter.** is
2caa0 20 69 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 ignored and the
2cab0 20 65 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74 end result is t
2cac0 68 65 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74 he same as sqlit
2cad0 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a e3_bind_null()..
2cae0 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 **.** ^(In those
2caf0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 routines that h
2cb00 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 ave a fourth arg
2cb10 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 ument, its value
2cb20 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 is the.** numbe
2cb30 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 r of bytes in th
2cb40 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f e parameter. To
2cb50 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 be clear: the v
2cb60 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e alue is the.** n
2cb70 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 umber of <u>byte
2cb80 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c s</u> in the val
2cb90 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 ue, not the numb
2cba0 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 er of characters
2cbb0 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 .)^.** ^If the f
2cbc0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
2cbd0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f to sqlite3_bind_
2cbe0 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 text() or sqlite
2cbf0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 3_bind_text16().
2cc00 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 ** is negative,
2cc10 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 then the length
2cc20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 of the string is
2cc30 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f .** the number o
2cc40 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 f bytes up to th
2cc50 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 e first zero ter
2cc60 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 minator..** If t
2cc70 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
2cc80 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 ter to sqlite3_b
2cc90 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 ind_blob() is ne
2cca0 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 gative, then.**
2ccb0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 the behavior is
2ccc0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 undefined..** If
2ccd0 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 a non-negative
2cce0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
2ccf0 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 is provided to
2cd00 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
2cd10 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 t().** or sqlite
2cd20 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 3_bind_text16()
2cd30 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f or sqlite3_bind_
2cd40 74 65 78 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a text64() then.**
2cd50 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 that parameter
2cd60 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65 must be the byte
2cd70 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 offset.** where
2cd80 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 the NUL termina
2cd90 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 tor would occur
2cda0 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 assuming the str
2cdb0 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 ing were NUL.**
2cdc0 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 terminated. If
2cdd0 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 any NUL characte
2cde0 72 73 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 rs occur at byte
2cdf0 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 offsets less th
2ce00 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 an .** the value
2ce10 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 of the fourth p
2ce20 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 arameter then th
2ce30 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 e resulting stri
2ce40 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a ng value will.**
2ce50 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 contain embedde
2ce60 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 d NULs. The res
2ce70 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f ult of expressio
2ce80 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 ns involving str
2ce90 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 ings.** with emb
2cea0 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e edded NULs is un
2ceb0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e defined..**.** ^
2cec0 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 The fifth argume
2ced0 6e 74 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 61 nt to the BLOB a
2cee0 6e 64 20 73 74 72 69 6e 67 20 62 69 6e 64 69 6e nd string bindin
2cef0 67 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 g interfaces.**
2cf00 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 is a destructor
2cf10 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 used to dispose
2cf20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a of the BLOB or.*
2cf30 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 * string after S
2cf40 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 QLite has finish
2cf50 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 ed with it. ^Th
2cf60 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 e destructor is
2cf70 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 called.** to dis
2cf80 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 pose of the BLOB
2cf90 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 or string even
2cfa0 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 62 if the call to b
2cfb0 69 6e 64 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a ind API fails..*
2cfc0 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 * ^If the fifth
2cfd0 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 argument is.** t
2cfe0 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 he special value
2cff0 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d [SQLITE_STATIC]
2d000 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 , then SQLite as
2d010 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a sumes that the.*
2d020 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 * information is
2d030 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 in static, unma
2d040 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 naged space and
2d050 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f does not need to
2d060 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 be freed..** ^I
2d070 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 f the fifth argu
2d080 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c ment has the val
2d090 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 ue [SQLITE_TRANS
2d0a0 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 IENT], then.** S
2d0b0 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 QLite makes its
2d0c0 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 own private copy
2d0d0 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d of the data imm
2d0e0 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 ediately, before
2d0f0 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f .** the sqlite3_
2d100 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 bind_*() routine
2d110 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 returns..**.**
2d120 5e 54 68 65 20 73 69 78 74 68 20 61 72 67 75 6d ^The sixth argum
2d130 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 ent to sqlite3_b
2d140 69 6e 64 5f 74 65 78 74 36 34 28 29 20 6d 75 73 ind_text64() mus
2d150 74 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b t be one of.** [
2d160 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 SQLITE_UTF8], [S
2d170 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 QLITE_UTF16], [S
2d180 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 QLITE_UTF16BE],
2d190 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 or [SQLITE_UTF16
2d1a0 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66 LE].** to specif
2d1b0 79 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f y the encoding o
2d1c0 66 20 74 68 65 20 74 65 78 74 20 69 6e 20 74 68 f the text in th
2d1d0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
2d1e0 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 73 69 r. If.** the si
2d1f0 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 xth argument to
2d200 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
2d210 74 36 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 t64() is not one
2d220 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 of the.** allow
2d230 65 64 20 76 61 6c 75 65 73 20 73 68 6f 77 6e 20 ed values shown
2d240 61 62 6f 76 65 2c 20 6f 72 20 69 66 20 74 68 65 above, or if the
2d250 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 text encoding i
2d260 73 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66 s different.** f
2d270 72 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 rom the encoding
2d280 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 specified by th
2d290 65 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 e sixth paramete
2d2a0 72 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 r, then the beha
2d2b0 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 vior.** is undef
2d2c0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ined..**.** ^The
2d2d0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 sqlite3_bind_ze
2d2e0 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 roblob() routine
2d2f0 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 binds a BLOB of
2d300 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a length N that.*
2d310 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 * is filled with
2d320 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 zeroes. ^A zer
2d330 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 oblob uses a fix
2d340 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d ed amount of mem
2d350 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 ory.** (just an
2d360 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 integer to hold
2d370 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 its size) while
2d380 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 it is being proc
2d390 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c essed..** Zerobl
2d3a0 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 obs are intended
2d3b0 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 to serve as pla
2d3c0 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c ceholders for BL
2d3d0 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e OBs whose.** con
2d3e0 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 tent is later wr
2d3f0 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b itten using.** [
2d400 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 sqlite3_blob_ope
2d410 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 n | incremental
2d420 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e BLOB I/O] routin
2d430 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 es..** ^A negati
2d440 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 ve value for the
2d450 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 zeroblob result
2d460 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 s in a zero-leng
2d470 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e th BLOB..**.** ^
2d480 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 If any of the sq
2d490 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 lite3_bind_*() r
2d4a0 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c outines are call
2d4b0 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 ed with a NULL p
2d4c0 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 ointer.** for th
2d4d0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
2d4e0 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 ement] or with a
2d4f0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
2d500 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a ent for which.**
2d510 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
2d520 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 ] has been calle
2d530 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 d more recently
2d540 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 than [sqlite3_re
2d550 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 set()],.** then
2d560 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 the call will re
2d570 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 turn [SQLITE_MIS
2d580 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 USE]. If any sq
2d590 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a lite3_bind_().**
2d5a0 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 routine is pass
2d5b0 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 ed a [prepared s
2d5c0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 tatement] that h
2d5d0 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 as been finalize
2d5e0 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 d, the.** result
2d5f0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e is undefined an
2d600 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 d probably harmf
2d610 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 ul..**.** ^Bindi
2d620 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 ngs are not clea
2d630 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 red by the [sqli
2d640 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 te3_reset()] rou
2d650 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e tine..** ^Unboun
2d660 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 d parameters are
2d670 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 interpreted as
2d680 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 NULL..**.** ^The
2d690 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 sqlite3_bind_*
2d6a0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
2d6b0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 [SQLITE_OK] on s
2d6c0 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 uccess or an.**
2d6d0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 [error code] if
2d6e0 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 anything goes wr
2d6f0 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 ong..** ^[SQLITE
2d700 5f 54 4f 4f 42 49 47 5d 20 6d 69 67 68 74 20 62 _TOOBIG] might b
2d710 65 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 e returned if th
2d720 65 20 73 69 7a 65 20 6f 66 20 61 20 73 74 72 69 e size of a stri
2d730 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 ng or BLOB.** ex
2d740 63 65 65 64 73 20 6c 69 6d 69 74 73 20 69 6d 70 ceeds limits imp
2d750 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 osed by [sqlite3
2d760 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f _limit]([SQLITE_
2d770 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 29 20 6f LIMIT_LENGTH]) o
2d780 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 r.** [SQLITE_MAX
2d790 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 _LENGTH]..** ^[S
2d7a0 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 QLITE_RANGE] is
2d7b0 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 returned if the
2d7c0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 parameter.** ind
2d7d0 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e ex is out of ran
2d7e0 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f ge. ^[SQLITE_NO
2d7f0 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 MEM] is returned
2d800 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 if malloc() fai
2d810 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c ls..**.** See al
2d820 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e so: [sqlite3_bin
2d830 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e d_parameter_coun
2d840 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 t()],.** [sqlite
2d850 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
2d860 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 _name()], and [s
2d870 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
2d880 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a meter_index()]..
2d890 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
2d8a0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
2d8b0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c sqlite3_bind_bl
2d8c0 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a ob(sqlite3_stmt*
2d8d0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 , int, const voi
2d8e0 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 d*, int n, void(
2d8f0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 *)(void*));.SQLI
2d900 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
2d910 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
2d920 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73 71 3_bind_blob64(sq
2d930 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
2d940 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 73 , const void*, s
2d950 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 qlite3_uint64,.
2d960 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2d970 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 void(*)(v
2d980 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 oid*));.SQLITE_A
2d990 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 PI int SQLITE_ST
2d9a0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 DCALL sqlite3_bi
2d9b0 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 nd_double(sqlite
2d9c0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 3_stmt*, int, do
2d9d0 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 uble);.SQLITE_AP
2d9e0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
2d9f0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e CALL sqlite3_bin
2da00 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 d_int(sqlite3_st
2da10 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a mt*, int, int);.
2da20 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
2da30 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
2da40 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 lite3_bind_int64
2da50 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
2da60 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 int, sqlite3_int
2da70 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64);.SQLITE_API
2da80 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 int SQLITE_STDCA
2da90 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f LL sqlite3_bind_
2daa0 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d null(sqlite3_stm
2dab0 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 t*, int);.SQLITE
2dac0 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f _API int SQLITE_
2dad0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
2dae0 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 bind_text(sqlite
2daf0 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 3_stmt*,int,cons
2db00 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 t char*,int,void
2db10 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c (*)(void*));.SQL
2db20 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 ITE_API int SQLI
2db30 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
2db40 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 e3_bind_text16(s
2db50 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
2db60 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 t, const void*,
2db70 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 int, void(*)(voi
2db80 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 d*));.SQLITE_API
2db90 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
2dba0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 ALL sqlite3_bind
2dbb0 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f _text64(sqlite3_
2dbc0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 stmt*, int, cons
2dbd0 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 t char*, sqlite3
2dbe0 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 _uint64,.
2dbf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2dc00 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 void(*)(void*)
2dc10 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 , unsigned char
2dc20 65 6e 63 6f 64 69 6e 67 29 3b 0a 53 51 4c 49 54 encoding);.SQLIT
2dc30 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
2dc40 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
2dc50 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 _bind_value(sqli
2dc60 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
2dc70 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 const sqlite3_va
2dc80 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 lue*);.SQLITE_AP
2dc90 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
2dca0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e CALL sqlite3_bin
2dcb0 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 d_zeroblob(sqlit
2dcc0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 e3_stmt*, int, i
2dcd0 6e 74 20 6e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 nt n);.SQLITE_AP
2dce0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
2dcf0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e CALL sqlite3_bin
2dd00 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73 71 6c d_zeroblob64(sql
2dd10 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c ite3_stmt*, int,
2dd20 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 sqlite3_uint64)
2dd30 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2dd40 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c F: Number Of SQL
2dd50 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 4d Parameters.** M
2dd60 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 ETHOD: sqlite3_s
2dd70 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 tmt.**.** ^This
2dd80 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 routine can be u
2dd90 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 sed to find the
2dda0 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 number of [SQL p
2ddb0 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e arameters].** in
2ddc0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
2ddd0 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 tement]. SQL pa
2dde0 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b rameters are tok
2ddf0 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f ens of the.** fo
2de00 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 rm "?", "?NNN",
2de10 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 ":AAA", "$AAA",
2de20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73 or "@AAA" that s
2de30 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 erve as.** place
2de40 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 holders for valu
2de50 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c es that are [sql
2de60 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c ite3_bind_blob |
2de70 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 bound].** to th
2de80 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 e parameters at
2de90 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a a later time..**
2dea0 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 .** ^(This routi
2deb0 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 ne actually retu
2dec0 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 rns the index of
2ded0 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 the largest (ri
2dee0 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 ghtmost).** para
2def0 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 meter. For all f
2df00 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e orms except ?NNN
2df10 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 , this will corr
2df20 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a espond to the.**
2df30 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 number of uniqu
2df40 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 e parameters. I
2df50 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 f parameters of
2df60 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 the ?NNN form ar
2df70 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 e used,.** there
2df80 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 may be gaps in
2df90 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a the list.)^.**.*
2dfa0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
2dfb0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 ite3_bind_blob|s
2dfc0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a qlite3_bind()],.
2dfd0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
2dfe0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 _parameter_name(
2dff0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 )], and.** [sqli
2e000 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
2e010 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a er_index()]..*/.
2e020 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
2e030 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
2e040 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
2e050 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 eter_count(sqlit
2e060 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a e3_stmt*);../*.*
2e070 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 * CAPI3REF: Name
2e080 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d Of A Host Param
2e090 65 74 65 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 eter.** METHOD:
2e0a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a sqlite3_stmt.**.
2e0b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
2e0c0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e bind_parameter_n
2e0d0 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 ame(P,N) interfa
2e0e0 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 ce returns.** th
2e0f0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d e name of the N-
2e100 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 th [SQL paramete
2e110 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 r] in the [prepa
2e120 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 red statement] P
2e130 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d ..** ^(SQL param
2e140 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 eters of the for
2e150 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 m "?NNN" or ":AA
2e160 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 A" or "@AAA" or
2e170 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 "$AAA".** have a
2e180 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 name which is t
2e190 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 he string "?NNN"
2e1a0 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 or ":AAA" or "@
2e1b0 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a AAA" or "$AAA".*
2e1c0 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a * respectively..
2e1d0 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 ** In other word
2e1e0 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 s, the initial "
2e1f0 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 :" or "$" or "@"
2e200 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e or "?".** is in
2e210 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f cluded as part o
2e220 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a f the name.)^.**
2e230 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 ^Parameters of
2e240 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 the form "?" wit
2e250 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 hout a following
2e260 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f integer have no
2e270 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 name.** and are
2e280 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 referred to as
2e290 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 "nameless" or "a
2e2a0 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 nonymous paramet
2e2b0 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ers"..**.** ^The
2e2c0 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 first host para
2e2d0 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 meter has an ind
2e2e0 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a ex of 1, not 0..
2e2f0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 **.** ^If the va
2e300 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 lue N is out of
2e310 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 range or if the
2e320 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 N-th parameter i
2e330 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 s.** nameless, t
2e340 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 hen NULL is retu
2e350 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 rned. ^The retu
2e360 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a rned string is.*
2e370 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d * always in UTF-
2e380 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 8 encoding even
2e390 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 if the named par
2e3a0 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 ameter was.** or
2e3b0 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 iginally specifi
2e3c0 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 ed as UTF-16 in
2e3d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
2e3e0 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 16()] or.** [sql
2e3f0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
2e400 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 2()]..**.** See
2e410 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 also: [sqlite3_b
2e420 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 ind_blob|sqlite3
2e430 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 _bind()],.** [sq
2e440 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
2e450 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 eter_count()], a
2e460 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 nd.** [sqlite3_b
2e470 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e ind_parameter_in
2e480 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 dex()]..*/.SQLIT
2e490 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 E_API const char
2e4a0 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c *SQLITE_STDCALL
2e4b0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 sqlite3_bind_pa
2e4c0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c rameter_name(sql
2e4d0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 ite3_stmt*, int)
2e4e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2e4f0 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 F: Index Of A Pa
2e500 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 rameter With A G
2e510 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 iven Name.** MET
2e520 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d HOD: sqlite3_stm
2e530 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 t.**.** ^Return
2e540 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 the index of an
2e550 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 SQL parameter gi
2e560 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e ven its name. ^
2e570 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c The.** index val
2e580 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 ue returned is s
2e590 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 uitable for use
2e5a0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a as the second.**
2e5b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 parameter to [s
2e5c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
2e5d0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d |sqlite3_bind()]
2e5e0 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 . ^A zero.** is
2e5f0 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 returned if no
2e600 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 matching paramet
2e610 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 er is found. ^T
2e620 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 he parameter.**
2e630 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 name must be giv
2e640 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e en in UTF-8 even
2e650 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c if the original
2e660 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 statement.** wa
2e670 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 s prepared from
2e680 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e UTF-16 text usin
2e690 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 g [sqlite3_prepa
2e6a0 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a re16_v2()]..**.*
2e6b0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
2e6c0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 ite3_bind_blob|s
2e6d0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a qlite3_bind()],.
2e6e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
2e6f0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 _parameter_count
2e700 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ()], and.** [sql
2e710 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
2e720 74 65 72 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2f 0a ter_name()]..*/.
2e730 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
2e740 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
2e750 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
2e760 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 eter_index(sqlit
2e770 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 e3_stmt*, const
2e780 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f char *zName);../
2e790 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
2e7a0 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 eset All Binding
2e7b0 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 s On A Prepared
2e7c0 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 Statement.** MET
2e7d0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d HOD: sqlite3_stm
2e7e0 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 t.**.** ^Contrar
2e7f0 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 y to the intuiti
2e800 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c on of many, [sql
2e810 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f ite3_reset()] do
2e820 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 es not reset.**
2e830 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e the [sqlite3_bin
2e840 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 d_blob | binding
2e850 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 s] on a [prepare
2e860 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a d statement]..**
2e870 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 ^Use this routi
2e880 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 ne to reset all
2e890 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 host parameters
2e8a0 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 to NULL..*/.SQLI
2e8b0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
2e8c0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
2e8d0 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 3_clear_bindings
2e8e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b (sqlite3_stmt*);
2e8f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2e900 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 : Number Of Colu
2e910 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 mns In A Result
2e920 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 Set.** METHOD: s
2e930 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a qlite3_stmt.**.*
2e940 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 * ^Return the nu
2e950 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 mber of columns
2e960 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 in the result se
2e970 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 t returned by th
2e980 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 e.** [prepared s
2e990 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 tatement]. ^This
2e9a0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
2e9b0 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 0 if pStmt is a
2e9c0 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 n SQL.** stateme
2e9d0 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 nt that does not
2e9e0 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f return data (fo
2e9f0 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 r example an [UP
2ea00 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 DATE])..**.** Se
2ea10 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 e also: [sqlite3
2ea20 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a _data_count()].*
2ea30 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
2ea40 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
2ea50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 sqlite3_column_c
2ea60 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d ount(sqlite3_stm
2ea70 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a t *pStmt);../*.*
2ea80 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 * CAPI3REF: Colu
2ea90 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 mn Names In A Re
2eaa0 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 sult Set.** METH
2eab0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 OD: sqlite3_stmt
2eac0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f .**.** ^These ro
2ead0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 utines return th
2eae0 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 e name assigned
2eaf0 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 to a particular
2eb00 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 column.** in the
2eb10 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 result set of a
2eb20 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d [SELECT] statem
2eb30 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 ent. ^The sqlit
2eb40 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 e3_column_name()
2eb50 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 .** interface re
2eb60 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
2eb70 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e to a zero-termin
2eb80 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e ated UTF-8 strin
2eb90 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 g.** and sqlite3
2eba0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 _column_name16()
2ebb0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
2ebc0 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 er to a zero-ter
2ebd0 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 minated.** UTF-1
2ebe0 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 6 string. ^The
2ebf0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
2ec00 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 is the [prepared
2ec10 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 statement].** t
2ec20 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 hat implements t
2ec30 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 he [SELECT] stat
2ec40 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f ement. ^The seco
2ec50 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 nd parameter is
2ec60 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 the.** column nu
2ec70 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 mber. ^The left
2ec80 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e most column is n
2ec90 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e umber 0..**.** ^
2eca0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 The returned str
2ecb0 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 ing pointer is v
2ecc0 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 alid until eithe
2ecd0 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 r the [prepared
2ece0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 statement].** is
2ecf0 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 destroyed by [s
2ed00 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
2ed10 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 )] or until the
2ed20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 statement is aut
2ed30 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 omatically.** re
2ed40 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 prepared by the
2ed50 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 first call to [s
2ed60 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 qlite3_step()] f
2ed70 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 or a particular
2ed80 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 run.** or until
2ed90 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f the next call to
2eda0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 .** sqlite3_colu
2edb0 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c mn_name() or sql
2edc0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 ite3_column_name
2edd0 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 16() on the same
2ede0 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e column..**.** ^
2edf0 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f If sqlite3_mallo
2ee00 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 c() fails during
2ee10 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 the processing
2ee20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e of either routin
2ee30 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c e.** (for exampl
2ee40 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 e during a conve
2ee50 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 rsion from UTF-8
2ee60 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e to UTF-16) then
2ee70 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 a.** NULL point
2ee80 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a er is returned..
2ee90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 **.** ^The name
2eea0 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 of a result colu
2eeb0 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 mn is the value
2eec0 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 of the "AS" clau
2eed0 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 se for.** that c
2eee0 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 olumn, if there
2eef0 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e is an AS clause.
2ef00 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f If there is no
2ef10 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 AS clause.** th
2ef20 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 en the name of t
2ef30 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 he column is uns
2ef40 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 pecified and may
2ef50 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 change from.**
2ef60 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 one release of S
2ef70 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 QLite to the nex
2ef80 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 t..*/.SQLITE_API
2ef90 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c const char *SQL
2efa0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
2efb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 te3_column_name(
2efc0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
2efd0 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 nt N);.SQLITE_AP
2efe0 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 I const void *SQ
2eff0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
2f000 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 ite3_column_name
2f010 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
2f020 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a , int N);../*.**
2f030 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 CAPI3REF: Sourc
2f040 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 e Of Data In A Q
2f050 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d uery Result.** M
2f060 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 ETHOD: sqlite3_s
2f070 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 tmt.**.** ^These
2f080 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 routines provid
2f090 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 e a means to det
2f0a0 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 ermine the datab
2f0b0 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a ase, table, and.
2f0c0 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 ** table column
2f0d0 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 that is the orig
2f0e0 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c in of a particul
2f0f0 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e ar result column
2f100 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 in.** [SELECT]
2f110 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 statement..** ^T
2f120 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 he name of the d
2f130 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 atabase or table
2f140 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 or column can b
2f150 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a e returned as.**
2f160 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 either a UTF-8
2f170 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 or UTF-16 string
2f180 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 . ^The _databas
2f190 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 e_ routines retu
2f1a0 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 rn.** the databa
2f1b0 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 se name, the _ta
2f1c0 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 ble_ routines re
2f1d0 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e turn the table n
2f1e0 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 ame, and.** the
2f1f0 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 origin_ routines
2f200 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 return the colu
2f210 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 mn name..** ^The
2f220 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 returned string
2f230 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 is valid until
2f240 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
2f250 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 atement] is dest
2f260 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b royed.** using [
2f270 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
2f280 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 ()] or until the
2f290 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 statement is au
2f2a0 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 tomatically.** r
2f2b0 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 eprepared by the
2f2c0 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b first call to [
2f2d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
2f2e0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 for a particular
2f2f0 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c run.** or until
2f300 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d the same inform
2f310 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 ation is request
2f320 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 ed.** again in a
2f330 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 different encod
2f340 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ing..**.** ^The
2f350 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 names returned a
2f360 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 re the original
2f370 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 un-aliased names
2f380 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 of the.** datab
2f390 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 ase, table, and
2f3a0 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 column..**.** ^T
2f3b0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
2f3c0 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 t to these inter
2f3d0 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 faces is a [prep
2f3e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e ared statement].
2f3f0 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 .** ^These funct
2f400 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f ions return info
2f410 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 rmation about th
2f420 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c e Nth result col
2f430 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a umn returned by.
2f440 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 ** the statement
2f450 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 , where N is the
2f460 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e second function
2f470 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 argument..** ^T
2f480 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c he left-most col
2f490 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 umn is column 0
2f4a0 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e for these routin
2f4b0 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 es..**.** ^If th
2f4c0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 e Nth column ret
2f4d0 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 urned by the sta
2f4e0 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 tement is an exp
2f4f0 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 ression or.** su
2f500 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f bquery and is no
2f510 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 t a column value
2f520 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 , then all of th
2f530 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 ese functions re
2f540 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e turn.** NULL. ^
2f550 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 These routine mi
2f560 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 ght also return
2f570 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 NULL if a memory
2f580 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f allocation erro
2f590 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f r.** occurs. ^O
2f5a0 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 therwise, they r
2f5b0 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f eturn the name o
2f5c0 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64 f the attached d
2f5d0 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a atabase, table,.
2f5e0 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 ** or column tha
2f5f0 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 t query result c
2f600 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 olumn was extrac
2f610 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 ted from..**.**
2f620 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 ^As with all oth
2f630 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 er SQLite APIs,
2f640 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 those whose name
2f650 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 s end with "16"
2f660 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 return.** UTF-16
2f670 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 encoded strings
2f680 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 and the other f
2f690 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 unctions return
2f6a0 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 UTF-8..**.** ^Th
2f6b0 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c ese APIs are onl
2f6c0 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 y available if t
2f6d0 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 he library was c
2f6e0 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 ompiled with the
2f6f0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 .** [SQLITE_ENAB
2f700 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 LE_COLUMN_METADA
2f710 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 TA] C-preprocess
2f720 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a or symbol..**.**
2f730 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 If two or more
2f740 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 threads call one
2f750 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 or more of thes
2f760 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e e routines again
2f770 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 st the same.** p
2f780 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2f790 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 t and column at
2f7a0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 the same time th
2f7b0 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 en the results a
2f7c0 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e re.** undefined.
2f7d0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 .**.** If two or
2f7e0 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 more threads ca
2f7f0 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a ll one or more.*
2f800 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d * [sqlite3_colum
2f810 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 n_database_name
2f820 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 | column metadat
2f830 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a a interfaces].**
2f840 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 for the same [p
2f850 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2f860 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f t] and result co
2f870 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 lumn.** at the s
2f880 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 ame time then th
2f890 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e e results are un
2f8a0 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 defined..*/.SQLI
2f8b0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 TE_API const cha
2f8c0 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c r *SQLITE_STDCAL
2f8d0 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e L sqlite3_column
2f8e0 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 _database_name(s
2f8f0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 qlite3_stmt*,int
2f900 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f );.SQLITE_API co
2f910 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 nst void *SQLITE
2f920 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
2f930 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 _column_database
2f940 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f _name16(sqlite3_
2f950 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 stmt*,int);.SQLI
2f960 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 TE_API const cha
2f970 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c r *SQLITE_STDCAL
2f980 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e L sqlite3_column
2f990 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 _table_name(sqli
2f9a0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a te3_stmt*,int);.
2f9b0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
2f9c0 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 void *SQLITE_ST
2f9d0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f DCALL sqlite3_co
2f9e0 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 lumn_table_name1
2f9f0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
2fa00 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 int);.SQLITE_API
2fa10 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c const char *SQL
2fa20 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
2fa30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 te3_column_origi
2fa40 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 n_name(sqlite3_s
2fa50 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 tmt*,int);.SQLIT
2fa60 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 E_API const void
2fa70 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c *SQLITE_STDCALL
2fa80 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2fa90 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 origin_name16(sq
2faa0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
2fab0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2fac0 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 F: Declared Data
2fad0 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 type Of A Query
2fae0 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 Result.** METHOD
2faf0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a : sqlite3_stmt.*
2fb00 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74 *.** ^(The first
2fb10 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 parameter is a
2fb20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2fb30 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 ent]..** If this
2fb40 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 statement is a
2fb50 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 [SELECT] stateme
2fb60 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 nt and the Nth c
2fb70 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 olumn of the.**
2fb80 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 returned result
2fb90 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c set of that [SEL
2fba0 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 ECT] is a table
2fbb0 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a column (not an.*
2fbc0 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 * expression or
2fbd0 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 subquery) then t
2fbe0 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 he declared type
2fbf0 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a of the table.**
2fc00 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 column is retur
2fc10 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 ned.)^ ^If the
2fc20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 Nth column of th
2fc30 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 e result set is
2fc40 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e an.** expression
2fc50 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 or subquery, th
2fc60 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 en a NULL pointe
2fc70 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a r is returned..*
2fc80 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 * ^The returned
2fc90 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 string is always
2fca0 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a UTF-8 encoded..
2fcb0 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d **.** ^(For exam
2fcc0 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 ple, given the d
2fcd0 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a atabase schema:.
2fce0 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 **.** CREATE TAB
2fcf0 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 LE t1(c1 VARIANT
2fd00 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 );.**.** and the
2fd10 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 following state
2fd20 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 ment to be compi
2fd30 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 led:.**.** SELEC
2fd40 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f T c1 + 1, c1 FRO
2fd50 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 M t1;.**.** this
2fd60 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 routine would r
2fd70 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 eturn the string
2fd80 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 "VARIANT" for t
2fd90 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 he second result
2fda0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 .** column (i==1
2fdb0 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f ), and a NULL po
2fdc0 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 inter for the fi
2fdd0 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d rst result colum
2fde0 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a n (i==0).)^.**.*
2fdf0 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64 * ^SQLite uses d
2fe00 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 ynamic run-time
2fe10 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 typing. ^So jus
2fe20 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 t because a colu
2fe30 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 mn.** is declare
2fe40 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 d to contain a p
2fe50 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 articular type d
2fe60 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 oes not mean tha
2fe70 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 t the.** data st
2fe80 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c ored in that col
2fe90 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 umn is of the de
2fea0 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 clared type. SQ
2feb0 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e Lite is.** stron
2fec0 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 gly typed, but t
2fed0 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e he typing is dyn
2fee0 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e amic not static.
2fef0 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 ^Type.** is as
2ff00 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e sociated with in
2ff10 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c dividual values,
2ff20 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f not with the co
2ff30 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 ntainers.** used
2ff40 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 to hold those v
2ff50 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 alues..*/.SQLITE
2ff60 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 _API const char
2ff70 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 *SQLITE_STDCALL
2ff80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 sqlite3_column_d
2ff90 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f ecltype(sqlite3_
2ffa0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 stmt*,int);.SQLI
2ffb0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 TE_API const voi
2ffc0 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c d *SQLITE_STDCAL
2ffd0 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e L sqlite3_column
2ffe0 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 _decltype16(sqli
2fff0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a te3_stmt*,int);.
30000 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
30010 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c Evaluate An SQL
30020 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 Statement.** ME
30030 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 THOD: sqlite3_st
30040 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 mt.**.** After a
30050 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
30060 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 ment] has been p
30070 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 repared using ei
30080 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ther.** [sqlite3
30090 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f _prepare_v2()] o
300a0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 r [sqlite3_prepa
300b0 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e re16_v2()] or on
300c0 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a e of the legacy.
300d0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 ** interfaces [s
300e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 qlite3_prepare()
300f0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 ] or [sqlite3_pr
30100 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 epare16()], this
30110 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 function.** mus
30120 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 t be called one
30130 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f or more times to
30140 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 evaluate the st
30150 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 atement..**.** T
30160 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 he details of th
30170 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 e behavior of th
30180 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 e sqlite3_step()
30190 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e interface depen
301a0 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 d.** on whether
301b0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 the statement wa
301c0 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 s prepared using
301d0 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 the newer "v2"
301e0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 interface.** [sq
301f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
30200 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
30210 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
30220 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 or the older le
30230 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 gacy.** interfac
30240 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 e [sqlite3_prepa
30250 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 re()] and [sqlit
30260 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e e3_prepare16()].
30270 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 The use of the
30280 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 .** new "v2" int
30290 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d erface is recomm
302a0 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 ended for new ap
302b0 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 plications but t
302c0 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 he legacy.** int
302d0 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 erface will cont
302e0 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f inue to be suppo
302f0 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 rted..**.** ^In
30300 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 the legacy inter
30310 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e face, the return
30320 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 value will be e
30330 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 ither [SQLITE_BU
30340 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f SY],.** [SQLITE_
30350 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 DONE], [SQLITE_R
30360 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 OW], [SQLITE_ERR
30370 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f OR], or [SQLITE_
30380 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 MISUSE]..** ^Wit
30390 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 h the "v2" inter
303a0 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 face, any of the
303b0 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 other [result c
303c0 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 odes] or.** [ext
303d0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
303e0 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 es] might be ret
303f0 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a urned as well..*
30400 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 *.** ^[SQLITE_BU
30410 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 SY] means that t
30420 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 he database engi
30430 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f ne was unable to
30440 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 acquire the.**
30450 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 database locks i
30460 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 t needs to do it
30470 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 s job. ^If the
30480 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b statement is a [
30490 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 COMMIT].** or oc
304a0 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 curs outside of
304b0 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e an explicit tran
304c0 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f saction, then yo
304d0 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a u can retry the.
304e0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 ** statement. I
304f0 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 f the statement
30500 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 is not a [COMMIT
30510 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 ] and occurs wit
30520 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 hin an.** explic
30530 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 it transaction t
30540 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 hen you should r
30550 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e ollback the tran
30560 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a saction before.*
30570 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a * continuing..**
30580 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e .** ^[SQLITE_DON
30590 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 E] means that th
305a0 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 e statement has
305b0 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 finished executi
305c0 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c ng.** successful
305d0 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 ly. sqlite3_ste
305e0 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 p() should not b
305f0 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f e called again o
30600 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a n this virtual.*
30610 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 * machine withou
30620 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 t first calling
30630 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
30640 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 ] to reset the v
30650 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e irtual.** machin
30660 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e e back to its in
30670 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a itial state..**.
30680 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 ** ^If the SQL s
30690 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 tatement being e
306a0 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 xecuted returns
306b0 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b any data, then [
306c0 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 SQLITE_ROW].** i
306d0 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 s returned each
306e0 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f time a new row o
306f0 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 f data is ready
30700 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 for processing b
30710 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e y the.** caller.
30720 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 The values may
30730 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e be accessed usin
30740 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 g the [column ac
30750 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e cess functions].
30760 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 .** sqlite3_step
30770 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 () is called aga
30780 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 in to retrieve t
30790 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 he next row of d
307a0 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c ata..**.** ^[SQL
307b0 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 ITE_ERROR] means
307c0 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 that a run-time
307d0 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 error (such as
307e0 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 a constraint.**
307f0 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f violation) has o
30800 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 ccurred. sqlite
30810 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 3_step() should
30820 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 not be called ag
30830 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d ain on.** the VM
30840 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 . More informati
30850 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 on may be found
30860 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 by calling [sqli
30870 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a te3_errmsg()]..*
30880 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 * ^With the lega
30890 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 cy interface, a
308a0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 more specific er
308b0 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 ror code (for ex
308c0 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 ample,.** [SQLIT
308d0 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 E_INTERRUPT], [S
308e0 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b QLITE_SCHEMA], [
308f0 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c SQLITE_CORRUPT],
30900 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a and so forth).*
30910 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 * can be obtaine
30920 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 d by calling [sq
30930 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f lite3_reset()] o
30940 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 n the.** [prepar
30950 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 ed statement].
30960 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 ^In the "v2" int
30970 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d erface,.** the m
30980 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 ore specific err
30990 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 or code is retur
309a0 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 ned directly by
309b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a sqlite3_step()..
309c0 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 **.** [SQLITE_MI
309d0 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 SUSE] means that
309e0 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e the this routin
309f0 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 e was called ina
30a00 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a ppropriately..**
30a10 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20 Perhaps it was
30a20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 called on a [pre
30a30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
30a40 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 that has.** alr
30a50 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 eady been [sqlit
30a60 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 e3_finalize | fi
30a70 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f nalized] or on o
30a80 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 ne that had.** p
30a90 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e reviously return
30aa0 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 ed [SQLITE_ERROR
30ab0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e ] or [SQLITE_DON
30ac0 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 E]. Or it could
30ad0 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 .** be the case
30ae0 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 that the same da
30af0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
30b00 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 n is being used
30b10 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 by two or.** mor
30b20 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 e threads at the
30b30 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 same moment in
30b40 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 time..**.** For
30b50 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 all versions of
30b60 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 SQLite up to and
30b70 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 including 3.6.2
30b80 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 3.1, a call to.*
30b90 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 * [sqlite3_reset
30ba0 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 ()] was required
30bb0 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 after sqlite3_s
30bc0 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 tep() returned a
30bd0 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 nything.** other
30be0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f than [SQLITE_RO
30bf0 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 W] before any su
30c00 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 bsequent invocat
30c10 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 ion of.** sqlite
30c20 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 3_step(). Failu
30c30 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 re to reset the
30c40 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
30c50 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 nt using .** [sq
30c60 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 lite3_reset()] w
30c70 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 ould result in a
30c80 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 n [SQLITE_MISUSE
30c90 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a ] return from.**
30ca0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e sqlite3_step().
30cb0 20 20 42 75 74 20 61 66 74 65 72 20 76 65 72 73 But after vers
30cc0 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 ion 3.6.23.1, sq
30cd0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 lite3_step() beg
30ce0 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 an.** calling [s
30cf0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
30d00 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e automatically in
30d10 20 74 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e this circumstan
30d20 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 ce rather.** tha
30d30 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c n returning [SQL
30d40 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 ITE_MISUSE]. Th
30d50 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 is is not consid
30d60 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 ered a compatibi
30d70 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 lity.** break be
30d80 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 cause any applic
30d90 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 ation that ever
30da0 72 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 receives an SQLI
30db0 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a TE_MISUSE error.
30dc0 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 ** is broken by
30dd0 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 definition. The
30de0 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 [SQLITE_OMIT_AU
30df0 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 TORESET] compile
30e00 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 -time option.**
30e10 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 can be used to r
30e20 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 estore the legac
30e30 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a y behavior..**.*
30e40 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 * <b>Goofy Inter
30e50 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 face Alert:</b>
30e60 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e In the legacy in
30e70 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c terface, the sql
30e80 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 ite3_step().** A
30e90 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e PI always return
30ea0 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f s a generic erro
30eb0 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f r code, [SQLITE_
30ec0 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e ERROR], followin
30ed0 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f g any.** error o
30ee0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 ther than [SQLIT
30ef0 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c E_BUSY] and [SQL
30f00 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f ITE_MISUSE]. Yo
30f10 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b u must call.** [
30f20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
30f30 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e or [sqlite3_fin
30f40 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 alize()] in orde
30f50 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 r to find one of
30f60 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 the.** specific
30f70 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 [error codes] t
30f80 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72 hat better descr
30f90 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a ibes the error..
30fa0 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 ** We admit that
30fb0 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 this is a goofy
30fc0 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 design. The pr
30fd0 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 oblem has been f
30fe0 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 ixed.** with the
30ff0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e "v2" interface.
31000 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 If you prepare
31010 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c all of your SQL
31020 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 statements.** u
31030 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c sing either [sql
31040 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
31050 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 )] or [sqlite3_p
31060 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 repare16_v2()] i
31070 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 nstead.** of the
31080 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 legacy [sqlite3
31090 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 _prepare()] and
310a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
310b0 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 16()] interfaces
310c0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f ,.** then the mo
310d0 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 re specific [err
310e0 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 or codes] are re
310f0 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a turned directly.
31100 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 ** by sqlite3_st
31110 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f ep(). The use o
31120 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 f the "v2" inter
31130 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e face is recommen
31140 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ded..*/.SQLITE_A
31150 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 PI int SQLITE_ST
31160 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 74 DCALL sqlite3_st
31170 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a ep(sqlite3_stmt*
31180 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
31190 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f EF: Number of co
311a0 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c lumns in a resul
311b0 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a t set.** METHOD:
311c0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a sqlite3_stmt.**
311d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
311e0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 _data_count(P) i
311f0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
31200 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 the number of c
31210 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a olumns in the.**
31220 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 current row of
31230 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f the result set o
31240 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 f [prepared stat
31250 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 ement] P..** ^If
31260 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
31270 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 ent P does not h
31280 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64 ave results read
31290 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 y to return.** (
312a0 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 via calls to the
312b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
312c0 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 _int | sqlite3_c
312d0 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a olumn_*()] of.**
312e0 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65 interfaces) the
312f0 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 n sqlite3_data_c
31300 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20 ount(P) returns
31310 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 0..** ^The sqlit
31320 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 e3_data_count(P)
31330 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 routine also re
31340 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20 turns 0 if P is
31350 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a a NULL pointer..
31360 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
31370 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f data_count(P) ro
31380 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 utine returns 0
31390 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 if the previous
313a0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 call to.** [sqli
313b0 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 te3_step](P) ret
313c0 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f urned [SQLITE_DO
313d0 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 NE]. ^The sqlit
313e0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 e3_data_count(P)
313f0 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 .** will return
31400 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 non-zero if prev
31410 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 ious call to [sq
31420 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 lite3_step](P) r
31430 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 eturned.** [SQLI
31440 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 TE_ROW], except
31450 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 74 in the case of t
31460 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 he [PRAGMA incre
31470 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a mental_vacuum].*
31480 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77 61 79 * where it alway
31490 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 s returns zero s
314a0 69 6e 63 65 20 65 61 63 68 20 73 74 65 70 20 6f ince each step o
314b0 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 f that multi-ste
314c0 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75 p.** pragma retu
314d0 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 rns 0 columns of
314e0 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 data..**.** See
314f0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f also: [sqlite3_
31500 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a column_count()].
31510 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
31520 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
31530 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f sqlite3_data_co
31540 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 unt(sqlite3_stmt
31550 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
31560 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 CAPI3REF: Funda
31570 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 mental Datatypes
31580 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 .** KEYWORDS: SQ
31590 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 LITE_TEXT.**.**
315a0 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e ^(Every value in
315b0 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 SQLite has one
315c0 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e of five fundamen
315d0 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a tal datatypes:.*
315e0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
315f0 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 > 64-bit signed
31600 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 integer.** <li>
31610 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 64-bit IEEE floa
31620 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 ting point numbe
31630 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 r.** <li> string
31640 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a .** <li> BLOB.**
31650 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f <li> NULL.** </
31660 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ul>)^.**.** Thes
31670 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 e constants are
31680 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f codes for each o
31690 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a f those types..*
316a0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 *.** Note that t
316b0 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 he SQLITE_TEXT c
316c0 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f onstant was also
316d0 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 used in SQLite
316e0 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 version 2.** for
316f0 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 a completely di
31700 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e fferent meaning.
31710 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 Software that
31720 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f links against bo
31730 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 th.** SQLite ver
31740 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 sion 2 and SQLit
31750 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 e version 3 shou
31760 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 ld use SQLITE3_T
31770 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 EXT, not.** SQLI
31780 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 TE_TEXT..*/.#def
31790 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 ine SQLITE_INTEG
317a0 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 ER 1.#define SQ
317b0 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a LITE_FLOAT 2.
317c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 #define SQLITE_B
317d0 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e LOB 4.#defin
317e0 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 e SQLITE_NULL
317f0 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 5.#ifdef SQLIT
31800 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 E_TEXT.# undef S
31810 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 QLITE_TEXT.#else
31820 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 .# define SQLITE
31830 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 _TEXT 3.#end
31840 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 if.#define SQLIT
31850 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f E3_TEXT 3../
31860 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
31870 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f esult Values Fro
31880 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 m A Query.** KEY
31890 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 WORDS: {column a
318a0 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d ccess functions}
318b0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
318c0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e te3_stmt.**.** ^
318d0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 These routines r
318e0 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f eturn informatio
318f0 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 n about a single
31900 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 column of the c
31910 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 urrent.** result
31920 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e row of a query.
31930 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 ^In every case
31940 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
31950 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 ent is a pointer
31960 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 .** to the [prep
31970 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
31980 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 that is being ev
31990 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 aluated (the [sq
319a0 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 lite3_stmt*].**
319b0 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 that was returne
319c0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f d from [sqlite3_
319d0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 prepare_v2()] or
319e0 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 one of its vari
319f0 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 ants).** and the
31a00 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
31a10 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 is the index of
31a20 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 the column for
31a30 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f which informatio
31a40 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 n.** should be r
31a50 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 eturned. ^The le
31a60 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 ftmost column of
31a70 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 the result set
31a80 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e has the index 0.
31a90 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 .** ^The number
31aa0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 of columns in th
31ab0 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 e result can be
31ac0 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 determined using
31ad0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c .** [sqlite3_col
31ae0 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a umn_count()]..**
31af0 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 .** If the SQL s
31b00 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f tatement does no
31b10 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e t currently poin
31b20 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 t to a valid row
31b30 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 , or if the.** c
31b40 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f olumn index is o
31b50 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 ut of range, the
31b60 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 result is undef
31b70 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 ined..** These r
31b80 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 outines may only
31b90 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 be called when
31ba0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 the most recent
31bb0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 call to.** [sqli
31bc0 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 te3_step()] has
31bd0 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 returned [SQLITE
31be0 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 _ROW] and neithe
31bf0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 r.** [sqlite3_re
31c00 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 set()] nor [sqli
31c10 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 te3_finalize()]
31c20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 have been called
31c30 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a subsequently..*
31c40 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 * If any of thes
31c50 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 e routines are c
31c60 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c alled after [sql
31c70 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 ite3_reset()] or
31c80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e .** [sqlite3_fin
31c90 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 alize()] or afte
31ca0 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 r [sqlite3_step(
31cb0 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a )] has returned.
31cc0 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 ** something oth
31cd0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f er than [SQLITE_
31ce0 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 ROW], the result
31cf0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e s are undefined.
31d00 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f .** If [sqlite3_
31d10 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 step()] or [sqli
31d20 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 te3_reset()] or
31d30 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
31d40 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c e()].** are call
31d50 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 ed from a differ
31d60 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 ent thread while
31d70 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f any of these ro
31d80 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 utines.** are pe
31d90 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 nding, then the
31da0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 results are unde
31db0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 fined..**.** ^Th
31dc0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e e sqlite3_column
31dd0 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 _type() routine
31de0 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b returns the.** [
31df0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c SQLITE_INTEGER |
31e00 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 datatype code]
31e10 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 for the initial
31e20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 data type.** of
31e30 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d the result colum
31e40 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 n. ^The returne
31e50 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f d value is one o
31e60 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 f [SQLITE_INTEGE
31e70 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 R],.** [SQLITE_F
31e80 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 LOAT], [SQLITE_T
31e90 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c EXT], [SQLITE_BL
31ea0 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f OB], or [SQLITE_
31eb0 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 NULL]. The valu
31ec0 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 e.** returned by
31ed0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
31ee0 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d type() is only m
31ef0 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 eaningful if no
31f00 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 type.** conversi
31f10 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 ons have occurre
31f20 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62 d as described b
31f30 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 elow. After a t
31f40 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a ype conversion,.
31f50 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 ** the value ret
31f60 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 urned by sqlite3
31f70 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 _column_type() i
31f80 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 s undefined. Fu
31f90 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 ture.** versions
31fa0 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 of SQLite may c
31fb0 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 hange the behavi
31fc0 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f or of sqlite3_co
31fd0 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 lumn_type().** f
31fe0 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 ollowing a type
31ff0 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a conversion..**.*
32000 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 * ^If the result
32010 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 is a BLOB or UT
32020 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 F-8 string then
32030 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 the sqlite3_colu
32040 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f mn_bytes().** ro
32050 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 utine returns th
32060 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
32070 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f s in that BLOB o
32080 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 r string..** ^If
32090 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 the result is a
320a0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 UTF-16 string,
320b0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c then sqlite3_col
320c0 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 umn_bytes() conv
320d0 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 erts.** the stri
320e0 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 ng to UTF-8 and
320f0 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 then returns the
32100 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
32110 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 ..** ^If the res
32120 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 ult is a numeric
32130 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 value then sqli
32140 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
32150 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 () uses.** [sqli
32160 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 te3_snprintf()]
32170 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 to convert that
32180 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 value to a UTF-8
32190 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 string and retu
321a0 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 rns.** the numbe
321b0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 r of bytes in th
321c0 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 at string..** ^I
321d0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 f the result is
321e0 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 NULL, then sqlit
321f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
32200 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a ) returns zero..
32210 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 **.** ^If the re
32220 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f sult is a BLOB o
32230 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 r UTF-16 string
32240 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 then the sqlite3
32250 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
32260 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 ).** routine ret
32270 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
32280 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 of bytes in that
32290 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e BLOB or string.
322a0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 .** ^If the resu
322b0 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 lt is a UTF-8 st
322c0 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 ring, then sqlit
322d0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
322e0 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 6() converts.**
322f0 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 the string to UT
32300 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 F-16 and then re
32310 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
32320 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 of bytes..** ^I
32330 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 f the result is
32340 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 a numeric value
32350 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c then sqlite3_col
32360 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 umn_bytes16() us
32370 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 es.** [sqlite3_s
32380 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f nprintf()] to co
32390 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 nvert that value
323a0 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 to a UTF-16 str
323b0 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a ing and returns.
323c0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ** the number of
323d0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 bytes in that s
323e0 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 tring..** ^If th
323f0 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c e result is NULL
32400 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 , then sqlite3_c
32410 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 olumn_bytes16()
32420 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a returns zero..**
32430 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 .** ^The values
32440 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c returned by [sql
32450 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
32460 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 s()] and .** [sq
32470 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
32480 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 es16()] do not i
32490 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 nclude the zero
324a0 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 terminators at t
324b0 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 he end.** of the
324c0 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 string. ^For c
324d0 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 larity: the valu
324e0 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a es returned by.*
324f0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d * [sqlite3_colum
32500 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b n_bytes()] and [
32510 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
32520 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 ytes16()] are th
32530 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 e number of.** b
32540 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 ytes in the stri
32550 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 ng, not the numb
32560 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 er of characters
32570 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 ..**.** ^Strings
32580 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c returned by sql
32590 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
325a0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 () and sqlite3_c
325b0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a olumn_text16(),.
325c0 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 ** even empty st
325d0 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 rings, are alway
325e0 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 s zero-terminate
325f0 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a d. ^The return.
32600 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 ** value from sq
32610 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f lite3_column_blo
32620 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c b() for a zero-l
32630 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 ength BLOB is a
32640 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a NULL pointer..**
32650 0a 2a 2a 20 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c .** <b>Warning:<
32660 2f 62 3e 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 /b> ^The object
32670 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c returned by [sql
32680 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 ite3_column_valu
32690 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 e()] is an.** [u
326a0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
326b0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
326c0 2e 20 20 49 6e 20 61 20 6d 75 6c 74 69 74 68 72 . In a multithr
326d0 65 61 64 65 64 20 65 6e 76 69 72 6f 6e 6d 65 6e eaded environmen
326e0 74 2c 0a 2a 2a 20 61 6e 20 75 6e 70 72 6f 74 65 t,.** an unprote
326f0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
32700 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 6f 6e ue object may on
32710 6c 79 20 62 65 20 75 73 65 64 20 73 61 66 65 6c ly be used safel
32720 79 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 y with.** [sqlit
32730 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d e3_bind_value()]
32740 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 and [sqlite3_re
32750 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a sult_value()]..*
32760 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 * If the [unprot
32770 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
32780 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 lue] object retu
32790 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 rned by.** [sqli
327a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 te3_column_value
327b0 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 ()] is used in a
327c0 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e ny other way, in
327d0 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a cluding calls.**
327e0 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b to routines lik
327f0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 e [sqlite3_value
32800 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 _int()], [sqlite
32810 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 3_value_text()],
32820 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f .** or [sqlite3_
32830 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 value_bytes()],
32840 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 the behavior is
32850 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 0a not threadsafe..
32860 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
32870 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 ines attempt to
32880 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 convert the valu
32890 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 e where appropri
328a0 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 ate. ^For.** ex
328b0 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e ample, if the in
328c0 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 ternal represent
328d0 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 ation is FLOAT a
328e0 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 nd a text result
328f0 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 .** is requested
32900 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 , [sqlite3_snpri
32910 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 ntf()] is used i
32920 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 nternally to per
32930 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 form the.** conv
32940 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 ersion automatic
32950 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c ally. ^(The fol
32960 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 lowing table det
32970 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 ails the convers
32980 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 ions.** that are
32990 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 applied:.**.**
329a0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 <blockquote>.**
329b0 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 <table border="1
329c0 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 ">.** <tr><th> I
329d0 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 nternal<br>Type
329e0 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 <th> Requested<b
329f0 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e r>Type <th> Con
32a00 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 version.**.** <t
32a10 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 r><td> NULL
32a20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c <td> INTEGER <
32a30 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a td> Result is 0.
32a40 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c ** <tr><td> NUL
32a50 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 L <td> FLOAT
32a60 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 <td> Result
32a70 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 is 0.0.** <tr><t
32a80 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e d> NULL <td>
32a90 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 TEXT <td>
32aa0 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c Result is a NULL
32ab0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e pointer.** <tr>
32ac0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 <td> NULL <t
32ad0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 d> BLOB <td
32ae0 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 > Result is a NU
32af0 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 LL pointer.** <t
32b00 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 r><td> INTEGER
32b10 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c <td> FLOAT <
32b20 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d td> Convert from
32b30 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 integer to floa
32b40 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e t.** <tr><td> IN
32b50 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 TEGER <td> TE
32b60 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 XT <td> ASCII
32b70 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 rendering of th
32b80 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 e integer.** <tr
32b90 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c ><td> INTEGER <
32ba0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 td> BLOB <t
32bb0 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 d> Same as INTEG
32bc0 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e ER->TEXT.** <tr>
32bd0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 <td> FLOAT <t
32be0 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 d> INTEGER <td
32bf0 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 > [CAST] to INTE
32c00 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 GER.** <tr><td>
32c10 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 FLOAT <td>
32c20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 TEXT <td> ASC
32c30 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 II rendering of
32c40 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 the float.** <tr
32c50 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c ><td> FLOAT <
32c60 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 td> BLOB <t
32c70 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f d> [CAST] to BLO
32c80 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 B.** <tr><td> T
32c90 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 EXT <td> INTE
32ca0 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 GER <td> [CAST
32cb0 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 ] to INTEGER.**
32cc0 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 <tr><td> TEXT
32cd0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 <td> FLOAT
32ce0 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 <td> [CAST] to
32cf0 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e REAL.** <tr><td>
32d00 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 TEXT <td>
32d10 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f BLOB <td> No
32d20 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c change.** <tr><
32d30 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 td> BLOB <td
32d40 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e > INTEGER <td>
32d50 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 [CAST] to INTEG
32d60 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 ER.** <tr><td>
32d70 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c BLOB <td> FL
32d80 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 OAT <td> [CAS
32d90 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 T] to REAL.** <t
32da0 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 r><td> BLOB
32db0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c <td> TEXT <
32dc0 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 td> Add a zero t
32dd0 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 erminator if nee
32de0 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a ded.** </table>.
32df0 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e ** </blockquote>
32e00 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 )^.**.** Note th
32e10 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e at when type con
32e20 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 versions occur,
32e30 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 pointers returne
32e40 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 d by prior.** ca
32e50 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 lls to sqlite3_c
32e60 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 olumn_blob(), sq
32e70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
32e80 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 t(), and/or.** s
32e90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
32ea0 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e xt16() may be in
32eb0 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 validated..** Ty
32ec0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 pe conversions a
32ed0 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c nd pointer inval
32ee0 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f idations might o
32ef0 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 ccur.** in the f
32f00 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a ollowing cases:.
32f10 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
32f20 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 i> The initial c
32f30 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 ontent is a BLOB
32f40 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c and sqlite3_col
32f50 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a umn_text() or.**
32f60 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f sqlite3_co
32f70 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 lumn_text16() is
32f80 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f called. A zero
32f90 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 -terminator migh
32fa0 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 t.** need t
32fb0 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 o be added to th
32fc0 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a e string.</li>.*
32fd0 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 * <li> The initi
32fe0 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 al content is UT
32ff0 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c F-8 text and sql
33000 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
33010 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 s16() or.**
33020 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
33030 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c text16() is call
33040 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 ed. The content
33050 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 must be convert
33060 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 ed.** to UT
33070 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c F-16.</li>.** <l
33080 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 i> The initial c
33090 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 ontent is UTF-16
330a0 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 text and sqlite
330b0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
330c0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 or.** sqli
330d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
330e0 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 ) is called. Th
330f0 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 e content must b
33100 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 e converted.**
33110 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c to UTF-8.</l
33120 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a i>.** </ul>.**.*
33130 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 * ^Conversions b
33140 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 etween UTF-16be
33150 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 and UTF-16le are
33160 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 always done in
33170 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 place and do.**
33180 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 not invalidate a
33190 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 prior pointer,
331a0 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 though of course
331b0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 the content of
331c0 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 the buffer.** th
331d0 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 at the prior poi
331e0 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 20 nter references
331f0 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d will have been m
33200 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 odified. Other
33210 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 kinds.** of conv
33220 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 ersion are done
33230 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 in place when it
33240 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 is possible, bu
33250 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 t sometimes they
33260 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 .** are not poss
33270 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 ible and in thos
33280 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f e cases prior po
33290 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c inters are inval
332a0 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 idated..**.** Th
332b0 65 20 73 61 66 65 73 74 20 70 6f 6c 69 63 79 20 e safest policy
332c0 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 is to invoke the
332d0 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 se routines.** i
332e0 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c n one of the fol
332f0 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a lowing ways:.**.
33300 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e ** <ul>.** <li>
33310 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
33320 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 ext() followed b
33330 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e y sqlite3_column
33340 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a _bytes()</li>.**
33350 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f <li>sqlite3_co
33360 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c lumn_blob() foll
33370 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f owed by sqlite3_
33380 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f column_bytes()</
33390 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 li>.** <li>sqli
333a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
333b0 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6() followed by
333c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
333d0 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a ytes16()</li>.**
333e0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 </ul>.**.** In
333f0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 other words, you
33400 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c should call sql
33410 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
33420 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 (),.** sqlite3_c
33430 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 olumn_blob(), or
33440 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
33450 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74 text16() first t
33460 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 o force the resu
33470 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 lt.** into the d
33480 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 esired format, t
33490 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 hen invoke sqlit
334a0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
334b0 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f ) or.** sqlite3_
334c0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
334d0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a to find the siz
334e0 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e e of the result.
334f0 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c Do not mix cal
33500 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 ls.** to sqlite3
33510 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f _column_text() o
33520 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e r sqlite3_column
33530 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c _blob() with cal
33540 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 ls to.** sqlite3
33550 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
33560 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 ), and do not mi
33570 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 x calls to sqlit
33580 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
33590 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 ().** with calls
335a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 to sqlite3_colu
335b0 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a mn_bytes()..**.*
335c0 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 * ^The pointers
335d0 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c returned are val
335e0 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 id until a type
335f0 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 conversion occur
33600 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 s as.** describe
33610 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 d above, or unti
33620 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 l [sqlite3_step(
33630 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 )] or [sqlite3_r
33640 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 eset()] or.** [s
33650 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
33660 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e )] is called. ^
33670 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 The memory space
33680 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 used to hold st
33690 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f rings.** and BLO
336a0 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f Bs is freed auto
336b0 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c matically. Do <
336c0 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 70 61 73 73 em>not</em> pass
336d0 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 the pointers re
336e0 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b turned.** from [
336f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
33700 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 lob()], [sqlite3
33710 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c _column_text()],
33720 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 etc. into.** [s
33730 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a qlite3_free()]..
33740 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d **.** ^(If a mem
33750 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 ory allocation e
33760 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 rror occurs duri
33770 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f ng the evaluatio
33780 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 n of any.** of t
33790 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 hese routines, a
337a0 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 default value i
337b0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 s returned. The
337c0 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a default value.*
337d0 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 * is either the
337e0 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 integer 0, the f
337f0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 loating point nu
33800 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e mber 0.0, or a N
33810 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 ULL.** pointer.
33820 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c Subsequent call
33830 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 s to [sqlite3_er
33840 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 rcode()] will re
33850 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f turn.** [SQLITE_
33860 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c NOMEM].)^.*/.SQL
33870 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f ITE_API const vo
33880 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 id *SQLITE_STDCA
33890 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d LL sqlite3_colum
338a0 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 n_blob(sqlite3_s
338b0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
338c0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
338d0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
338e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
338f0 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 tes(sqlite3_stmt
33900 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 *, int iCol);.SQ
33910 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
33920 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
33930 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
33940 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
33950 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c , int iCol);.SQL
33960 49 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 53 ITE_API double S
33970 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
33980 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 lite3_column_dou
33990 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ble(sqlite3_stmt
339a0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 *, int iCol);.SQ
339b0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
339c0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
339d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 te3_column_int(s
339e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
339f0 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f t iCol);.SQLITE_
33a00 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 API sqlite3_int6
33a10 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 4 SQLITE_STDCALL
33a20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
33a30 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 int64(sqlite3_st
33a40 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
33a50 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
33a60 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a unsigned char *
33a70 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
33a80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
33a90 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a xt(sqlite3_stmt*
33aa0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c , int iCol);.SQL
33ab0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f ITE_API const vo
33ac0 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 id *SQLITE_STDCA
33ad0 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d LL sqlite3_colum
33ae0 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 n_text16(sqlite3
33af0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
33b00 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
33b10 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
33b20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
33b30 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d type(sqlite3_stm
33b40 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 t*, int iCol);.S
33b50 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 QLITE_API sqlite
33b60 33 5f 76 61 6c 75 65 20 2a 53 51 4c 49 54 45 5f 3_value *SQLITE_
33b70 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
33b80 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c column_value(sql
33b90 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
33ba0 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 iCol);../*.** CA
33bb0 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 PI3REF: Destroy
33bc0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 A Prepared State
33bd0 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 44 ment Object.** D
33be0 45 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 ESTRUCTOR: sqlit
33bf0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 e3_stmt.**.** ^T
33c00 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c he sqlite3_final
33c10 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 ize() function i
33c20 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 s called to dele
33c30 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 te a [prepared s
33c40 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 tatement]..** ^I
33c50 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e f the most recen
33c60 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 t evaluation of
33c70 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e the statement en
33c80 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 countered no err
33c90 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 ors.** or if the
33ca0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 statement is ne
33cb0 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 ver been evaluat
33cc0 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 ed, then sqlite3
33cd0 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 _finalize() retu
33ce0 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b rns.** SQLITE_OK
33cf0 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 . ^If the most
33d00 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f recent evaluatio
33d10 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 n of statement S
33d20 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a failed, then.**
33d30 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a sqlite3_finaliz
33d40 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 e(S) returns the
33d50 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 appropriate [er
33d60 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 ror code] or.**
33d70 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 [extended error
33d80 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 code]..**.** ^Th
33d90 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 e sqlite3_finali
33da0 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 ze(S) routine ca
33db0 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 n be called at a
33dc0 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a ny point during.
33dd0 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c ** the life cycl
33de0 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 e of [prepared s
33df0 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 tatement] S:.**
33e00 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 before statement
33e10 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 S is ever evalu
33e20 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f ated, after.** o
33e30 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 ne or more calls
33e40 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 to [sqlite3_res
33e50 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 et()], or after
33e60 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b any call.** to [
33e70 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
33e80 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 regardless of wh
33e90 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 ether or not the
33ea0 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a statement has.*
33eb0 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 * completed exec
33ec0 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e ution..**.** ^In
33ed0 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 voking sqlite3_f
33ee0 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e inalize() on a N
33ef0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 ULL pointer is a
33f00 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e harmless no-op.
33f10 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 .**.** The appli
33f20 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 cation must fina
33f30 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 lize every [prep
33f40 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
33f50 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 in order to avoi
33f60 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 d.** resource le
33f70 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 aks. It is a gr
33f80 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 ievous error for
33f90 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
33fa0 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a to try to use.*
33fb0 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 * a prepared sta
33fc0 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 tement after it
33fd0 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a has been finaliz
33fe0 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 ed. Any use of
33ff0 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 a prepared.** st
34000 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 atement after it
34010 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 has been finali
34020 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 zed can result i
34030 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a n undefined and.
34040 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 ** undesirable b
34050 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 ehavior such as
34060 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 segfaults and he
34070 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a ap corruption..*
34080 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
34090 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
340a0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
340b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 (sqlite3_stmt *p
340c0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 Stmt);../*.** CA
340d0 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 PI3REF: Reset A
340e0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 Prepared Stateme
340f0 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4d 45 54 nt Object.** MET
34100 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d HOD: sqlite3_stm
34110 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 t.**.** The sqli
34120 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 te3_reset() func
34130 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 tion is called t
34140 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 o reset a [prepa
34150 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a red statement].*
34160 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f * object back to
34170 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 its initial sta
34180 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 te, ready to be
34190 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 re-executed..**
341a0 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 ^Any SQL stateme
341b0 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 nt variables tha
341c0 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 t had values bou
341d0 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 nd to them using
341e0 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 .** the [sqlite3
341f0 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c _bind_blob | sql
34200 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 ite3_bind_*() AP
34210 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 I] retain their
34220 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b values..** Use [
34230 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 sqlite3_clear_bi
34240 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 ndings()] to res
34250 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e et the bindings.
34260 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c .**.** ^The [sql
34270 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 ite3_reset(S)] i
34280 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20 nterface resets
34290 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
342a0 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 atement] S.** ba
342b0 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e ck to the beginn
342c0 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 ing of its progr
342d0 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 am..**.** ^If th
342e0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 e most recent ca
342f0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 ll to [sqlite3_s
34300 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a tep(S)] for the.
34310 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ** [prepared sta
34320 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e tement] S return
34330 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 ed [SQLITE_ROW]
34340 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d or [SQLITE_DONE]
34350 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 ,.** or if [sqli
34360 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 te3_step(S)] has
34370 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 never before be
34380 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a en called on S,.
34390 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 ** then [sqlite3
343a0 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 _reset(S)] retur
343b0 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a ns [SQLITE_OK]..
343c0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f **.** ^If the mo
343d0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 st recent call t
343e0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 o [sqlite3_step(
343f0 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b S)] for the.** [
34400 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
34410 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 nt] S indicated
34420 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a an error, then.*
34430 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 * [sqlite3_reset
34440 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 (S)] returns an
34450 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 appropriate [err
34460 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 or code]..**.**
34470 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 ^The [sqlite3_re
34480 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 set(S)] interfac
34490 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 e does not chang
344a0 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 e the values.**
344b0 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f of any [sqlite3_
344c0 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e bind_blob|bindin
344d0 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 gs] on the [prep
344e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
344f0 53 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 S..*/.SQLITE_API
34500 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
34510 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 73 65 ALL sqlite3_rese
34520 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a t(sqlite3_stmt *
34530 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 pStmt);../*.** C
34540 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 API3REF: Create
34550 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 Or Redefine SQL
34560 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 Functions.** KEY
34570 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e WORDS: {function
34580 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e creation routin
34590 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a es}.** KEYWORDS:
345a0 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 {application-de
345b0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 fined SQL functi
345c0 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a on}.** KEYWORDS:
345d0 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 {application-de
345e0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 fined SQL functi
345f0 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 ons}.** METHOD:
34600 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 sqlite3.**.** ^T
34610 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 hese functions (
34620 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f collectively kno
34630 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 wn as "function
34640 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 creation routine
34650 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 s").** are used
34660 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 to add SQL funct
34670 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 ions or aggregat
34680 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e es or to redefin
34690 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a e the behavior.*
346a0 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 * of existing SQ
346b0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 L functions or a
346c0 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 ggregates. The
346d0 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 only differences
346e0 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 between.** thes
346f0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 e routines are t
34700 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 he text encoding
34710 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a expected for.**
34720 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 the second para
34730 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 meter (the name
34740 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 of the function
34750 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a being created).*
34760 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e * and the presen
34770 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 ce or absence of
34780 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 a destructor ca
34790 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 llback for.** th
347a0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 e application da
347b0 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a ta pointer..**.*
347c0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 * ^The first par
347d0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 ameter is the [d
347e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
347f0 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 on] to which the
34800 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e SQL.** function
34810 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e is to be added.
34820 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 ^If an applica
34830 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 tion uses more t
34840 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 han one database
34850 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 .** connection t
34860 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d hen application-
34870 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
34880 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 tions must be ad
34890 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 ded.** to each d
348a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
348b0 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a on separately..*
348c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 *.** ^The second
348d0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
348e0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 e name of the SQ
348f0 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 L function to be
34900 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 created or.** r
34910 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 edefined. ^The
34920 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 length of the na
34930 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f me is limited to
34940 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 255 bytes in a
34950 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 UTF-8.** represe
34960 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 ntation, exclusi
34970 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 ve of the zero-t
34980 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 erminator. ^Not
34990 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a e that the name.
349a0 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 ** length limit
349b0 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 is in UTF-8 byte
349c0 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 s, not character
349d0 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 s nor UTF-16 byt
349e0 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 es. .** ^Any at
349f0 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 tempt to create
34a00 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 a function with
34a10 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a a longer name.**
34a20 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 will result in
34a30 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 [SQLITE_MISUSE]
34a40 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a being returned..
34a50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 **.** ^The third
34a60 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 parameter (nArg
34a70 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 ).** is the numb
34a80 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 er of arguments
34a90 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e that the SQL fun
34aa0 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 ction or.** aggr
34ab0 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 egate takes. ^If
34ac0 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 this parameter
34ad0 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 is -1, then the
34ae0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a SQL function or.
34af0 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 ** aggregate may
34b00 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 take any number
34b10 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 of arguments be
34b20 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 tween 0 and the
34b30 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 limit.** set by
34b40 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 [sqlite3_limit](
34b50 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 [SQLITE_LIMIT_FU
34b60 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 NCTION_ARG]). I
34b70 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 f the third.** p
34b80 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 arameter is less
34b90 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 than -1 or grea
34ba0 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 ter than 127 the
34bb0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 n the behavior i
34bc0 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a s.** undefined..
34bd0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 **.** ^The fourt
34be0 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 h parameter, eTe
34bf0 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 xtRep, specifies
34c00 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 what.** [SQLITE
34c10 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 _UTF8 | text enc
34c20 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 oding] this SQL
34c30 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 function prefers
34c40 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 for.** its para
34c50 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61 70 70 meters. The app
34c60 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 lication should
34c70 73 65 74 20 74 68 69 73 20 70 61 72 61 6d 65 74 set this paramet
34c80 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 er to.** [SQLITE
34c90 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68 65 _UTF16LE] if the
34ca0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d function implem
34cb0 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 entation invokes
34cc0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 .** [sqlite3_va
34cd0 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d 20 lue_text16le()]
34ce0 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20 on an input, or
34cf0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d [SQLITE_UTF16BE]
34d00 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 if the.** imple
34d10 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 mentation invoke
34d20 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 s [sqlite3_value
34d30 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e 20 _text16be()] on
34d40 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 an input, or.**
34d50 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 69 [SQLITE_UTF16] i
34d60 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 f [sqlite3_value
34d70 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20 75 73 _text16()] is us
34d80 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 ed, or [SQLITE_U
34d90 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73 TF8].** otherwis
34da0 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53 51 e. ^The same SQ
34db0 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 L function may b
34dc0 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c e registered mul
34dd0 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69 6e tiple times usin
34de0 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20 70 g.** different p
34df0 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e referred text en
34e00 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64 69 codings, with di
34e10 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e fferent implemen
34e20 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 tations for.** e
34e30 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a ach encoding..**
34e40 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 ^When multiple
34e50 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
34e60 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 of the same func
34e70 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 tion are availab
34e80 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 le, SQLite.** wi
34e90 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 ll pick the one
34ea0 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 that involves th
34eb0 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f e least amount o
34ec0 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f f data conversio
34ed0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f n..**.** ^The fo
34ee0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6d urth parameter m
34ef0 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65 ay optionally be
34f00 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c 49 ORed with [SQLI
34f10 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 TE_DETERMINISTIC
34f20 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74 ].** to signal t
34f30 68 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f 6e hat the function
34f40 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 will always ret
34f50 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65 73 urn the same res
34f60 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65 ult given.** the
34f70 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69 74 same inputs wit
34f80 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51 4c hin a single SQL
34f90 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 statement. Mos
34fa0 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 t SQL functions
34fb0 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69 are.** determini
34fc0 73 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c 74 stic. The built
34fd0 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 -in [random()] S
34fe0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 QL function is a
34ff0 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a n example of a.*
35000 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 * function that
35010 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69 is not determini
35020 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69 74 stic. The SQLit
35030 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 e query planner
35040 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 is able to.** pe
35050 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c rform additional
35060 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f optimizations o
35070 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 20 n deterministic
35080 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73 functions, so us
35090 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c e.** of the [SQL
350a0 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 ITE_DETERMINISTI
350b0 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f 6d C] flag is recom
350c0 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f 73 mended where pos
350d0 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 sible..**.** ^(T
350e0 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 he fifth paramet
350f0 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 er is an arbitra
35100 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 ry pointer. The
35110 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
35120 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 of the.** functi
35130 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 on can gain acce
35140 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 ss to this point
35150 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 er using [sqlite
35160 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 3_user_data()].)
35170 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 ^.**.** ^The six
35180 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20 th, seventh and
35190 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72 eighth parameter
351a0 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 s, xFunc, xStep
351b0 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a and xFinal, are.
351c0 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 ** pointers to C
351d0 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 -language functi
351e0 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 ons that impleme
351f0 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 nt the SQL funct
35200 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 ion or.** aggreg
35210 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 ate. ^A scalar S
35220 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 QL function requ
35230 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e ires an implemen
35240 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 tation of the xF
35250 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 unc.** callback
35260 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 only; NULL point
35270 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73 ers must be pass
35280 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20 ed as the xStep
35290 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 and xFinal.** pa
352a0 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 rameters. ^An ag
352b0 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 gregate SQL func
352c0 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e tion requires an
352d0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
352e0 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 of xStep.** and
352f0 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 xFinal and NULL
35300 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20 pointer must be
35310 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 passed for xFunc
35320 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 . ^To delete an
35330 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 existing.** SQL
35340 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 function or aggr
35350 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c egate, pass NULL
35360 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c pointers for al
35370 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e l three function
35380 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a .** callbacks..*
35390 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 *.** ^(If the ni
353a0 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f nth parameter to
353b0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
353c0 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 function_v2() is
353d0 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 not NULL,.** th
353e0 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63 en it is destruc
353f0 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c tor for the appl
35400 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 ication data poi
35410 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 nter. .** The de
35420 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f structor is invo
35430 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e ked when the fun
35440 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 ction is deleted
35450 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e , either by bein
35460 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 g.** overloaded
35470 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 or when the data
35480 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
35490 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 closes.)^.** ^Th
354a0 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 e destructor is
354b0 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 also invoked if
354c0 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 the call to.** s
354d0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
354e0 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c nction_v2() fail
354f0 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 s..** ^When the
35500 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 destructor callb
35510 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68 ack of the tenth
35520 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e parameter is in
35530 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 voked, it.** is
35540 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20 passed a single
35550 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 argument which i
35560 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 s a copy of the
35570 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 application data
35580 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 .** pointer whi
35590 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68 ch was the fifth
355a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
355b0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
355c0 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a ction_v2()..**.*
355d0 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 * ^It is permitt
355e0 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d ed to register m
355f0 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e ultiple implemen
35600 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 tations of the s
35610 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 ame.** functions
35620 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e with the same n
35630 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74 ame but with eit
35640 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 her differing nu
35650 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 mbers of.** argu
35660 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 ments or differi
35670 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78 ng preferred tex
35680 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 t encodings. ^S
35690 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a QLite will use.*
356a0 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 * the implementa
356b0 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 tion that most c
356c0 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 losely matches t
356d0 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 he way in which
356e0 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 the.** SQL funct
356f0 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 ion is used. ^A
35700 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d function implem
35710 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 entation with a
35720 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 non-negative.**
35730 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 nArg parameter i
35740 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 s a better match
35750 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e than a function
35760 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
35770 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 with.** a negati
35780 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e ve nArg. ^A fun
35790 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 ction where the
357a0 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 preferred text e
357b0 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 ncoding.** match
357c0 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 es the database
357d0 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 encoding is a be
357e0 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 tter.** match th
357f0 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 an a function wh
35800 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 ere the encoding
35810 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 is different.
35820 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 .** ^A function
35830 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 where the encodi
35840 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 ng difference is
35850 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 between UTF16le
35860 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 and UTF16be.**
35870 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 is a closer matc
35880 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f h than a functio
35890 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f n where the enco
358a0 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 ding difference
358b0 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 is.** between UT
358c0 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a F8 and UTF16..**
358d0 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 .** ^Built-in fu
358e0 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f nctions may be o
358f0 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 verloaded by new
35900 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
35910 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a ined functions..
35920 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 **.** ^An applic
35930 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
35940 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 nction is permit
35950 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 ted to call othe
35960 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 r.** SQLite inte
35970 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 rfaces. However
35980 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 , such calls mus
35990 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 t not.** close t
359a0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
359b0 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c ection nor final
359c0 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 ize or reset the
359d0 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 prepared.** sta
359e0 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 tement in which
359f0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 the function is
35a00 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 running..*/.SQLI
35a10 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
35a20 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
35a30 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
35a40 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 n(. sqlite3 *db
35a50 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a ,. const char *
35a60 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 zFunctionName,.
35a70 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 int nArg,. int
35a80 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 eTextRep,. voi
35a90 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 d *pApp,. void
35aa0 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 (*xFunc)(sqlite3
35ab0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 _context*,int,sq
35ac0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a lite3_value**),.
35ad0 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 void (*xStep)(
35ae0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
35af0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c ,int,sqlite3_val
35b00 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a ue**),. void (*
35b10 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f xFinal)(sqlite3_
35b20 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c context*).);.SQL
35b30 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 ITE_API int SQLI
35b40 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
35b50 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
35b60 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 on16(. sqlite3
35b70 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 *db,. const voi
35b80 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 d *zFunctionName
35b90 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 ,. int nArg,.
35ba0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 int eTextRep,.
35bb0 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f void *pApp,. vo
35bc0 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 id (*xFunc)(sqli
35bd0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 te3_context*,int
35be0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a ,sqlite3_value**
35bf0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 ),. void (*xSte
35c00 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 p)(sqlite3_conte
35c10 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f xt*,int,sqlite3_
35c20 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 value**),. void
35c30 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 (*xFinal)(sqlit
35c40 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a e3_context*).);.
35c50 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
35c60 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
35c70 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
35c80 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 ction_v2(. sqli
35c90 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 te3 *db,. const
35ca0 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e char *zFunction
35cb0 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 Name,. int nArg
35cc0 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 ,. int eTextRep
35cd0 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a ,. void *pApp,.
35ce0 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 void (*xFunc)(
35cf0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
35d00 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c ,int,sqlite3_val
35d10 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a ue**),. void (*
35d20 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 xStep)(sqlite3_c
35d30 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 ontext*,int,sqli
35d40 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 te3_value**),.
35d50 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 void (*xFinal)(s
35d60 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 qlite3_context*)
35d70 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 ,. void(*xDestr
35d80 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f oy)(void*).);../
35d90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 *.** CAPI3REF: T
35da0 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a ext Encodings.**
35db0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 .** These consta
35dc0 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 nt define intege
35dd0 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 r codes that rep
35de0 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f resent the vario
35df0 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 us.** text encod
35e00 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 ings supported b
35e10 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 y SQLite..*/.#de
35e20 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 fine SQLITE_UTF8
35e30 20 20 20 20 20 20 20 20 20 20 20 31 20 20 20 20 1
35e40 2f 2a 20 49 4d 50 3a 20 52 2d 33 37 35 31 34 2d /* IMP: R-37514-
35e50 33 35 35 36 36 20 2a 2f 0a 23 64 65 66 69 6e 65 35566 */.#define
35e60 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 SQLITE_UTF16LE
35e70 20 20 20 20 20 20 20 32 20 20 20 20 2f 2a 20 49 2 /* I
35e80 4d 50 3a 20 52 2d 30 33 33 37 31 2d 33 37 36 33 MP: R-03371-3763
35e90 37 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 7 */.#define SQL
35ea0 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 ITE_UTF16BE
35eb0 20 20 20 33 20 20 20 20 2f 2a 20 49 4d 50 3a 20 3 /* IMP:
35ec0 52 2d 35 31 39 37 31 2d 33 34 31 35 34 20 2a 2f R-51971-34154 */
35ed0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
35ee0 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34 UTF16 4
35ef0 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 /* Use nativ
35f00 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a e byte order */.
35f10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
35f20 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20 NY 5
35f30 20 20 20 2f 2a 20 44 65 70 72 65 63 61 74 65 64 /* Deprecated
35f40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
35f50 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 TE_UTF16_ALIGNED
35f60 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 8 /* sqlite
35f70 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
35f80 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a on only */../*.*
35f90 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 * CAPI3REF: Func
35fa0 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a tion Flags.**.**
35fb0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 These constants
35fc0 20 6d 61 79 20 62 65 20 4f 52 65 64 20 74 6f 67 may be ORed tog
35fd0 65 74 68 65 72 20 77 69 74 68 20 74 68 65 20 0a ether with the .
35fe0 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 ** [SQLITE_UTF8
35ff0 7c 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 | preferred text
36000 20 65 6e 63 6f 64 69 6e 67 5d 20 61 73 20 74 68 encoding] as th
36010 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e e fourth argumen
36020 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 t.** to [sqlite3
36030 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
36040 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 ()], [sqlite3_cr
36050 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 eate_function16(
36060 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 )], or.** [sqlit
36070 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
36080 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65 on_v2()]..*/.#de
36090 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 45 fine SQLITE_DETE
360a0 52 4d 49 4e 49 53 54 49 43 20 20 20 20 30 78 38 RMINISTIC 0x8
360b0 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 00../*.** CAPI3R
360c0 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 EF: Deprecated F
360d0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 unctions.** DEPR
360e0 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 ECATED.**.** The
360f0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 se functions are
36100 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 [deprecated].
36110 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e In order to main
36120 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 tain.** backward
36130 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 s compatibility
36140 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c with older code,
36150 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 these functions
36160 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f continue .** to
36170 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 be supported.
36180 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 However, new app
36190 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 lications should
361a0 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 avoid.** the us
361b0 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 e of these funct
361c0 69 6f 6e 73 2e 20 20 54 6f 20 65 6e 63 6f 75 72 ions. To encour
361d0 61 67 65 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 age programmers
361e0 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 73 to avoid.** thes
361f0 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 e functions, we
36200 77 69 6c 6c 20 6e 6f 74 20 65 78 70 6c 61 69 6e will not explain
36210 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a what they do..*
36220 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 /.#ifndef SQLITE
36230 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 _OMIT_DEPRECATED
36240 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 .SQLITE_API SQLI
36250 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e TE_DEPRECATED in
36260 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
36270 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 sqlite3_aggrega
36280 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 te_count(sqlite3
36290 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 _context*);.SQLI
362a0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 TE_API SQLITE_DE
362b0 50 52 45 43 41 54 45 44 20 69 6e 74 20 53 51 4c PRECATED int SQL
362c0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
362d0 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 te3_expired(sqli
362e0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 te3_stmt*);.SQLI
362f0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 TE_API SQLITE_DE
36300 50 52 45 43 41 54 45 44 20 69 6e 74 20 53 51 4c PRECATED int SQL
36310 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
36320 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e te3_transfer_bin
36330 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 dings(sqlite3_st
36340 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d mt*, sqlite3_stm
36350 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 t*);.SQLITE_API
36360 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 SQLITE_DEPRECATE
36370 44 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 D int SQLITE_STD
36380 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 67 6c 6f CALL sqlite3_glo
36390 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 bal_recover(void
363a0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 );.SQLITE_API SQ
363b0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 LITE_DEPRECATED
363c0 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 void SQLITE_STDC
363d0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74 68 72 65 ALL sqlite3_thre
363e0 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 ad_cleanup(void)
363f0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c ;.SQLITE_API SQL
36400 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 ITE_DEPRECATED i
36410 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c nt SQLITE_STDCAL
36420 4c 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 L sqlite3_memory
36430 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 _alarm(void(*)(v
36440 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 oid*,sqlite3_int
36450 36 34 2c 69 6e 74 29 2c 0a 20 20 20 20 20 20 20 64,int),.
36460 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 v
36470 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 oid*,sqlite3_int
36480 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 64);.#endif../*.
36490 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 ** CAPI3REF: Obt
364a0 61 69 6e 69 6e 67 20 53 51 4c 20 56 61 6c 75 65 aining SQL Value
364b0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c s.** METHOD: sql
364c0 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a ite3_value.**.**
364d0 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 The C-language
364e0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
364f0 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 f SQL functions
36500 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75 and aggregates u
36510 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 ses.** this set
36520 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 of interface rou
36530 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 tines to access
36540 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 the parameter va
36550 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 lues on.** the f
36560 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 unction or aggre
36570 67 61 74 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 gate. .**.** Th
36580 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 e xFunc (for sca
36590 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f lar functions) o
365a0 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 r xStep (for agg
365b0 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 regates) paramet
365c0 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 ers.** to [sqlit
365d0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
365e0 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 on()] and [sqlit
365f0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
36600 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e on16()].** defin
36610 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 e callbacks that
36620 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 implement the S
36630 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 QL functions and
36640 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 aggregates..**
36650 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 The 3rd paramete
36660 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 r to these callb
36670 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 acks is an array
36680 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a of pointers to.
36690 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 ** [protected sq
366a0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
366b0 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 ects. There is
366c0 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c one [sqlite3_val
366d0 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a ue] object for.*
366e0 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 * each parameter
366f0 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 to the SQL func
36700 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 tion. These rou
36710 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 tines are used t
36720 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c o.** extract val
36730 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 ues from the [sq
36740 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
36750 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ects..**.** Thes
36760 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 e routines work
36770 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 only with [prote
36780 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
36790 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 ue] objects..**
367a0 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 Any attempt to u
367b0 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 se these routine
367c0 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 s on an [unprote
367d0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
367e0 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 ue].** object re
367f0 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e sults in undefin
36800 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a ed behavior..**.
36810 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e ** ^These routin
36820 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b es work just lik
36830 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 e the correspond
36840 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 ing [column acce
36850 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a ss functions].**
36860 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65 except that the
36870 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 se routines take
36880 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 a single [prote
36890 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
368a0 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f ue] object.** po
368b0 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 inter instead of
368c0 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 a [sqlite3_stmt
368d0 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 *] pointer and a
368e0 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e n integer column
368f0 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e number..**.** ^
36900 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 The sqlite3_valu
36910 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 e_text16() inter
36920 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61 20 face extracts a
36930 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a UTF-16 string.**
36940 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 in the native b
36950 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 yte-order of the
36960 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 host machine.
36970 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f ^The.** sqlite3_
36980 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 value_text16be()
36990 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c and sqlite3_val
369a0 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e ue_text16le() in
369b0 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 terfaces.** extr
369c0 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e act UTF-16 strin
369d0 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e gs as big-endian
369e0 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 and little-endi
369f0 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e an respectively.
36a00 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c .**.** ^(The sql
36a10 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 ite3_value_numer
36a20 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 ic_type() interf
36a30 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 ace attempts to
36a40 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 apply.** numeric
36a50 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 affinity to the
36a60 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 value. This me
36a70 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 ans that an atte
36a80 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 mpt is.** made t
36a90 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 o convert the va
36aa0 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 lue to an intege
36ab0 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f r or floating po
36ac0 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 int. If.** such
36ad0 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 a conversion is
36ae0 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 possible withou
36af0 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d t loss of inform
36b00 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a ation (in other.
36b10 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 ** words, if the
36b20 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 value is a stri
36b30 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 ng that looks li
36b40 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 ke a number).**
36b50 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 then the convers
36b60 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 ion is performed
36b70 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 . Otherwise no
36b80 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 conversion occur
36b90 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 s..** The [SQLIT
36ba0 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 E_INTEGER | data
36bb0 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 type] after conv
36bc0 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e ersion is return
36bd0 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 ed.)^.**.** Plea
36be0 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 se pay particula
36bf0 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 r attention to t
36c00 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65 he fact that the
36c10 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65 pointer returne
36c20 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 d.** from [sqlit
36c30 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d e3_value_blob()]
36c40 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 , [sqlite3_value
36c50 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 _text()], or.**
36c60 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 [sqlite3_value_t
36c70 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 ext16()] can be
36c80 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 invalidated by a
36c90 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c subsequent call
36ca0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
36cb0 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 value_bytes()],
36cc0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 [sqlite3_value_b
36cd0 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 ytes16()], [sqli
36ce0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 te3_value_text()
36cf0 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 ],.** or [sqlite
36d00 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 3_value_text16()
36d10 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 ]..**.** These r
36d20 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 outines must be
36d30 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 called from the
36d40 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a same thread as.*
36d50 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 * the SQL functi
36d60 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 on that supplied
36d70 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 the [sqlite3_va
36d80 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 lue*] parameters
36d90 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
36da0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 const void *SQLI
36db0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
36dc0 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 e3_value_blob(sq
36dd0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 lite3_value*);.S
36de0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 QLITE_API int SQ
36df0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
36e00 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 ite3_value_bytes
36e10 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
36e20 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
36e30 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
36e40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 sqlite3_value_by
36e50 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 tes16(sqlite3_va
36e60 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 lue*);.SQLITE_AP
36e70 49 20 64 6f 75 62 6c 65 20 53 51 4c 49 54 45 5f I double SQLITE_
36e80 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
36e90 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c value_double(sql
36ea0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 ite3_value*);.SQ
36eb0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
36ec0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
36ed0 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 te3_value_int(sq
36ee0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 lite3_value*);.S
36ef0 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 QLITE_API sqlite
36f00 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 3_int64 SQLITE_S
36f10 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 TDCALL sqlite3_v
36f20 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 alue_int64(sqlit
36f30 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 e3_value*);.SQLI
36f40 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 TE_API const uns
36f50 69 67 6e 65 64 20 63 68 61 72 20 2a 53 51 4c 49 igned char *SQLI
36f60 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
36f70 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 e3_value_text(sq
36f80 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 lite3_value*);.S
36f90 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
36fa0 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 void *SQLITE_STD
36fb0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c CALL sqlite3_val
36fc0 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 ue_text16(sqlite
36fd0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 3_value*);.SQLIT
36fe0 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 E_API const void
36ff0 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c *SQLITE_STDCALL
37000 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
37010 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f ext16le(sqlite3_
37020 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f value*);.SQLITE_
37030 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a API const void *
37040 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
37050 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
37060 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 t16be(sqlite3_va
37070 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 lue*);.SQLITE_AP
37080 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
37090 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c CALL sqlite3_val
370a0 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f ue_type(sqlite3_
370b0 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f value*);.SQLITE_
370c0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 API int SQLITE_S
370d0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 TDCALL sqlite3_v
370e0 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 alue_numeric_typ
370f0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a e(sqlite3_value*
37100 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
37110 45 46 3a 20 46 69 6e 64 69 6e 67 20 54 68 65 20 EF: Finding The
37120 53 75 62 74 79 70 65 20 4f 66 20 53 51 4c 20 56 Subtype Of SQL V
37130 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a alues.** METHOD:
37140 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a sqlite3_value.*
37150 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
37160 5f 76 61 6c 75 65 5f 73 75 62 74 79 70 65 28 56 _value_subtype(V
37170 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 ) function retur
37180 6e 73 20 74 68 65 20 73 75 62 74 79 70 65 20 66 ns the subtype f
37190 6f 72 0a 2a 2a 20 61 6e 20 5b 61 70 70 6c 69 63 or.** an [applic
371a0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 ation-defined SQ
371b0 4c 20 66 75 6e 63 74 69 6f 6e 5d 20 61 72 67 75 L function] argu
371c0 6d 65 6e 74 20 56 2e 20 20 54 68 65 20 73 75 62 ment V. The sub
371d0 74 79 70 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 type.** informat
371e0 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 ion can be used
371f0 74 6f 20 70 61 73 73 20 61 20 6c 69 6d 69 74 65 to pass a limite
37200 64 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 d amount of cont
37210 65 78 74 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 ext from.** one
37220 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 SQL function to
37230 61 6e 6f 74 68 65 72 2e 20 20 55 73 65 20 74 68 another. Use th
37240 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c e [sqlite3_resul
37250 74 5f 73 75 62 74 79 70 65 28 29 5d 0a 2a 2a 20 t_subtype()].**
37260 72 6f 75 74 69 6e 65 20 74 6f 20 73 65 74 20 74 routine to set t
37270 68 65 20 73 75 62 74 79 70 65 20 66 6f 72 20 74 he subtype for t
37280 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
37290 6f 66 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 of an SQL functi
372a0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 on..**.** SQLite
372b0 20 6d 61 6b 65 73 20 6e 6f 20 75 73 65 20 6f 66 makes no use of
372c0 20 73 75 62 74 79 70 65 20 69 74 73 65 6c 66 2e subtype itself.
372d0 20 20 49 74 20 6d 65 72 65 6c 79 20 70 61 73 73 It merely pass
372e0 65 73 20 74 68 65 20 73 75 62 74 79 70 65 0a 2a es the subtype.*
372f0 2a 20 66 72 6f 6d 20 74 68 65 20 72 65 73 75 6c * from the resul
37300 74 20 6f 66 20 6f 6e 65 20 5b 61 70 70 6c 69 63 t of one [applic
37310 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 ation-defined SQ
37320 4c 20 66 75 6e 63 74 69 6f 6e 5d 20 69 6e 74 6f L function] into
37330 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 20 6f 66 the.** input of
37340 20 61 6e 6f 74 68 65 72 2e 0a 2a 2f 0a 53 51 4c another..*/.SQL
37350 49 54 45 5f 41 50 49 20 75 6e 73 69 67 6e 65 64 ITE_API unsigned
37360 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
37370 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ALL sqlite3_valu
37380 65 5f 73 75 62 74 79 70 65 28 73 71 6c 69 74 65 e_subtype(sqlite
37390 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 3_value*);../*.*
373a0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 70 79 * CAPI3REF: Copy
373b0 20 41 6e 64 20 46 72 65 65 20 53 51 4c 20 56 61 And Free SQL Va
373c0 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 lues.** METHOD:
373d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a sqlite3_value.**
373e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
373f0 5f 76 61 6c 75 65 5f 64 75 70 28 56 29 20 69 6e _value_dup(V) in
37400 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 terface makes a
37410 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c copy of the [sql
37420 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f ite3_value].** o
37430 62 6a 65 63 74 20 44 20 61 6e 64 20 72 65 74 75 bject D and retu
37440 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
37450 20 74 68 61 74 20 63 6f 70 79 2e 20 20 5e 54 68 that copy. ^Th
37460 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 e [sqlite3_value
37470 5d 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 ] returned.** is
37480 20 61 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 a [protected sq
37490 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
374a0 65 63 74 20 65 76 65 6e 20 69 66 20 74 68 65 20 ect even if the
374b0 69 6e 70 75 74 20 69 73 20 6e 6f 74 2e 0a 2a 2a input is not..**
374c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 ^The sqlite3_va
374d0 6c 75 65 5f 64 75 70 28 56 29 20 69 6e 74 65 72 lue_dup(V) inter
374e0 66 61 63 65 20 72 65 74 75 72 6e 73 20 4e 55 4c face returns NUL
374f0 4c 20 69 66 20 56 20 69 73 20 4e 55 4c 4c 20 6f L if V is NULL o
37500 72 20 69 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 r if a.** memory
37510 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c allocation fail
37520 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 s..**.** ^The sq
37530 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 lite3_value_free
37540 28 56 29 20 69 6e 74 65 72 66 61 63 65 20 66 72 (V) interface fr
37550 65 65 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f ees an [sqlite3_
37560 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a value] object.**
37570 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 previously obta
37580 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 ined from [sqlit
37590 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d 2e e3_value_dup()].
375a0 20 20 5e 49 66 20 56 20 69 73 20 61 20 4e 55 4c ^If V is a NUL
375b0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 L pointer.** the
375c0 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f n sqlite3_value_
375d0 66 72 65 65 28 56 29 20 69 73 20 61 20 68 61 72 free(V) is a har
375e0 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a mless no-op..*/.
375f0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
37600 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 73 E_EXPERIMENTAL s
37610 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 53 51 qlite3_value *SQ
37620 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
37630 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 63 ite3_value_dup(c
37640 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c onst sqlite3_val
37650 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ue*);.SQLITE_API
37660 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 SQLITE_EXPERIME
37670 4e 54 41 4c 20 76 6f 69 64 20 53 51 4c 49 54 45 NTAL void SQLITE
37680 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
37690 5f 76 61 6c 75 65 5f 66 72 65 65 28 73 71 6c 69 _value_free(sqli
376a0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a te3_value*);../*
376b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 .** CAPI3REF: Ob
376c0 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 tain Aggregate F
376d0 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a unction Context.
376e0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
376f0 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a e3_context.**.**
37700 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 Implementations
37710 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51 of aggregate SQ
37720 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 L functions use
37730 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 this.** routine
37740 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f to allocate memo
37750 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 ry for storing t
37760 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a heir state..**.*
37770 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d * ^The first tim
37780 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 e the sqlite3_ag
37790 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 gregate_context(
377a0 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 C,N) routine is
377b0 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 called .** for a
377c0 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 particular aggr
377d0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 egate function,
377e0 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 SQLite.** alloca
377f0 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c tes N of memory,
37800 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 zeroes out that
37810 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 memory, and ret
37820 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a urns a pointer.*
37830 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d * to the new mem
37840 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 ory. ^On second
37850 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 and subsequent c
37860 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 alls to.** sqlit
37870 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
37880 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 text() for the s
37890 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 ame aggregate fu
378a0 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c nction instance,
378b0 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 .** the same buf
378c0 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e fer is returned.
378d0 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 Sqlite3_aggreg
378e0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 ate_context() is
378f0 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c normally.** cal
37900 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 led once for eac
37910 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 h invocation of
37920 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 the xStep callba
37930 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a ck and then one.
37940 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 ** last time whe
37950 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c n the xFinal cal
37960 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 lback is invoked
37970 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 . ^(When no row
37980 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 s match.** an ag
37990 67 72 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 gregate query, t
379a0 68 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 he xStep() callb
379b0 61 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 ack of the aggre
379c0 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a gate function.**
379d0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
379e0 69 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 is never called
379f0 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 and xFinal() is
37a00 63 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f called exactly o
37a10 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 nce..** In those
37a20 20 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f cases, sqlite3_
37a30 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 aggregate_contex
37a40 74 28 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c t() might be cal
37a50 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 led for the.** f
37a60 69 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 irst time from w
37a70 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 ithin xFinal().)
37a80 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ^.**.** ^The sql
37a90 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
37aa0 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 ontext(C,N) rout
37ab0 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 ine returns a NU
37ac0 4c 4c 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 LL pointer .** w
37ad0 68 65 6e 20 66 69 72 73 74 20 63 61 6c 6c 65 64 hen first called
37ae0 20 69 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 if N is less th
37af0 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a an or equal to z
37b00 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f ero or if a memo
37b10 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65 ry.** allocate e
37b20 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a rror occurs..**.
37b30 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 ** ^(The amount
37b40 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 of space allocat
37b50 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67 ed by sqlite3_ag
37b60 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 gregate_context(
37b70 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 C,N) is.** deter
37b80 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70 mined by the N p
37b90 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 arameter on firs
37ba0 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c t successful cal
37bb0 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65 l. Changing the
37bc0 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 .** value of N i
37bd0 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c n subsequent cal
37be0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 l to sqlite3_agg
37bf0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 regate_context()
37c00 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 within.** the s
37c10 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 ame aggregate fu
37c20 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 nction instance
37c30 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 will not resize
37c40 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c the memory.** al
37c50 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74 location.)^ Wit
37c60 68 69 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 hin the xFinal c
37c70 61 6c 6c 62 61 63 6b 2c 20 69 74 20 69 73 20 63 allback, it is c
37c80 75 73 74 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a ustomary to set.
37c90 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20 ** N=0 in calls
37ca0 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 to sqlite3_aggre
37cb0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e gate_context(C,N
37cc0 29 20 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a ) so that no .**
37cd0 20 70 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 pointless memor
37ce0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 y allocations oc
37cf0 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 cur..**.** ^SQLi
37d00 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 te automatically
37d10 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 frees the memor
37d20 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a y allocated by .
37d30 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 ** sqlite3_aggre
37d40 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 gate_context() w
37d50 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 hen the aggregat
37d60 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 e query conclude
37d70 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 s..**.** The fir
37d80 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 st parameter mus
37d90 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 t be a copy of t
37da0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 he.** [sqlite3_c
37db0 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e ontext | SQL fun
37dc0 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 ction context] t
37dd0 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74 hat is the first
37de0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f parameter.** to
37df0 20 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 the xStep or xF
37e00 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f inal callback ro
37e10 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 utine that imple
37e20 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 ments the aggreg
37e30 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e ate.** function.
37e40 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
37e50 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c ine must be call
37e60 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 ed from the same
37e70 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 thread in which
37e80 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 .** the aggregat
37e90 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 e SQL function i
37ea0 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 s running..*/.SQ
37eb0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 LITE_API void *S
37ec0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
37ed0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
37ee0 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f context(sqlite3_
37ef0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 context*, int nB
37f00 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ytes);../*.** CA
37f10 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 PI3REF: User Dat
37f20 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a a For Functions.
37f30 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
37f40 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a e3_context.**.**
37f50 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 ^The sqlite3_us
37f60 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 er_data() interf
37f70 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f ace returns a co
37f80 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 py of.** the poi
37f90 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68 nter that was th
37fa0 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61 e pUserData para
37fb0 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70 meter (the 5th p
37fc0 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 arameter).** of
37fd0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 the [sqlite3_cre
37fe0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a ate_function()].
37ff0 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ** and [sqlite3_
38000 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 create_function1
38010 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 6()] routines th
38020 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a at originally.**
38030 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 registered the
38040 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 application defi
38050 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a ned function..**
38060 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 .** This routine
38070 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 must be called
38080 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 from the same th
38090 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a read in which.**
380a0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
380b0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
380c0 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f n is running..*/
380d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
380e0 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c *SQLITE_STDCALL
380f0 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 sqlite3_user_da
38100 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ta(sqlite3_conte
38110 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 xt*);../*.** CAP
38120 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 I3REF: Database
38130 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 Connection For F
38140 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 unctions.** METH
38150 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 OD: sqlite3_cont
38160 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ext.**.** ^The s
38170 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 qlite3_context_d
38180 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 b_handle() inter
38190 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 face returns a c
381a0 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f opy of.** the po
381b0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 inter to the [da
381c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
381d0 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61 n] (the 1st para
381e0 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 meter).** of the
381f0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
38200 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 _function()].**
38210 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 and [sqlite3_cre
38220 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 ate_function16()
38230 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 ] routines that
38240 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 originally.** re
38250 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 gistered the app
38260 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 lication defined
38270 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 function..*/.SQ
38280 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 LITE_API sqlite3
38290 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c *SQLITE_STDCALL
382a0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 sqlite3_context
382b0 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 _db_handle(sqlit
382c0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f e3_context*);../
382d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 *.** CAPI3REF: F
382e0 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 unction Auxiliar
382f0 79 20 44 61 74 61 0a 2a 2a 20 4d 45 54 48 4f 44 y Data.** METHOD
38300 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 : sqlite3_contex
38310 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 t.**.** These fu
38320 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 nctions may be u
38330 73 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72 sed by (non-aggr
38340 65 67 61 74 65 29 20 53 51 4c 20 66 75 6e 63 74 egate) SQL funct
38350 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 ions to.** assoc
38360 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 iate metadata wi
38370 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 th argument valu
38380 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 es. If the same
38390 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 value is passed
383a0 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 to.** multiple i
383b0 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 nvocations of th
383c0 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 e same SQL funct
383d0 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 ion during query
383e0 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 execution, unde
383f0 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d r.** some circum
38400 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f stances the asso
38410 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 ciated metadata
38420 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64 may be preserved
38430 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a . An example.**
38440 20 6f 66 20 77 68 65 72 65 20 74 68 69 73 20 6d of where this m
38450 69 67 68 74 20 62 65 20 75 73 65 66 75 6c 20 69 ight be useful i
38460 73 20 69 6e 20 61 20 72 65 67 75 6c 61 72 2d 65 s in a regular-e
38470 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 xpression matchi
38480 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 ng.** function.
38490 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 The compiled ver
384a0 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 sion of the regu
384b0 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 lar expression c
384c0 61 6e 20 62 65 20 73 74 6f 72 65 64 20 61 73 0a an be stored as.
384d0 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f ** metadata asso
384e0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 ciated with the
384f0 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 2e 20 pattern string.
38500 20 0a 2a 2a 20 54 68 65 6e 20 61 73 20 6c 6f 6e .** Then as lon
38510 67 20 61 73 20 74 68 65 20 70 61 74 74 65 72 6e g as the pattern
38520 20 73 74 72 69 6e 67 20 72 65 6d 61 69 6e 73 20 string remains
38530 74 68 65 20 73 61 6d 65 2c 0a 2a 2a 20 74 68 65 the same,.** the
38540 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 compiled regula
38550 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e r expression can
38560 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 be reused on mu
38570 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 ltiple.** invoca
38580 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d tions of the sam
38590 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a e function..**.*
385a0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 * ^The sqlite3_g
385b0 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 et_auxdata() int
385c0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 erface returns a
385d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
385e0 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f metadata.** asso
385f0 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71 ciated by the sq
38600 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 lite3_set_auxdat
38610 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 a() function wit
38620 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 h the Nth argume
38630 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 nt.** value to t
38640 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
38650 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e efined function.
38660 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f ^If there is no
38670 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 metadata.** ass
38680 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 ociated with the
38690 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 function argume
386a0 6e 74 2c 20 74 68 69 73 20 73 71 6c 69 74 65 33 nt, this sqlite3
386b0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 _get_auxdata() i
386c0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 nterface.** retu
386d0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 rns a NULL point
386e0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 er..**.** ^The s
386f0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 qlite3_set_auxda
38700 74 61 28 43 2c 4e 2c 50 2c 58 29 20 69 6e 74 65 ta(C,N,P,X) inte
38710 72 66 61 63 65 20 73 61 76 65 73 20 50 20 61 73 rface saves P as
38720 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 metadata for th
38730 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 e N-th.** argume
38740 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 nt of the applic
38750 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
38760 6e 63 74 69 6f 6e 2e 20 20 5e 53 75 62 73 65 71 nction. ^Subseq
3