System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact de5a5898ebd3a3477d4652db143746d008b24c83:


0000: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
0010: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0020: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0030: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0040: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
0050: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 69 73 20  ** This file is 
0060: 61 6e 20 61 6d 61 6c 67 61 6d 61 74 69 6f 6e 20  an amalgamation 
0070: 6f 66 20 6d 61 6e 79 20 73 65 70 61 72 61 74 65  of many separate
0080: 20 43 20 73 6f 75 72 63 65 20 66 69 6c 65 73 20   C source files 
0090: 66 72 6f 6d 20 53 51 4c 69 74 65 0a 2a 2a 20 76  from SQLite.** v
00a0: 65 72 73 69 6f 6e 20 33 2e 31 32 2e 32 2e 20 20  ersion 3.12.2.  
00b0: 42 79 20 63 6f 6d 62 69 6e 69 6e 67 20 61 6c 6c  By combining all
00c0: 20 74 68 65 20 69 6e 64 69 76 69 64 75 61 6c 20   the individual 
00d0: 43 20 63 6f 64 65 20 66 69 6c 65 73 20 69 6e 74  C code files int
00e0: 6f 20 74 68 69 73 20 0a 2a 2a 20 73 69 6e 67 6c  o this .** singl
00f0: 65 20 6c 61 72 67 65 20 66 69 6c 65 2c 20 74 68  e large file, th
0100: 65 20 65 6e 74 69 72 65 20 63 6f 64 65 20 63 61  e entire code ca
0110: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 61 73  n be compiled as
0120: 20 61 20 73 69 6e 67 6c 65 20 74 72 61 6e 73 6c   a single transl
0130: 61 74 69 6f 6e 0a 2a 2a 20 75 6e 69 74 2e 20 20  ation.** unit.  
0140: 54 68 69 73 20 61 6c 6c 6f 77 73 20 6d 61 6e 79  This allows many
0150: 20 63 6f 6d 70 69 6c 65 72 73 20 74 6f 20 64 6f   compilers to do
0160: 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 74   optimizations t
0170: 68 61 74 20 77 6f 75 6c 64 20 6e 6f 74 20 62 65  hat would not be
0180: 0a 2a 2a 20 70 6f 73 73 69 62 6c 65 20 69 66 20  .** possible if 
0190: 74 68 65 20 66 69 6c 65 73 20 77 65 72 65 20 63  the files were c
01a0: 6f 6d 70 69 6c 65 64 20 73 65 70 61 72 61 74 65  ompiled separate
01b0: 6c 79 2e 20 20 50 65 72 66 6f 72 6d 61 6e 63 65  ly.  Performance
01c0: 20 69 6d 70 72 6f 76 65 6d 65 6e 74 73 0a 2a 2a   improvements.**
01d0: 20 6f 66 20 35 25 20 6f 72 20 6d 6f 72 65 20 61   of 5% or more a
01e0: 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 73 65 65 6e  re commonly seen
01f0: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
0200: 63 6f 6d 70 69 6c 65 64 20 61 73 20 61 20 73 69  compiled as a si
0210: 6e 67 6c 65 0a 2a 2a 20 74 72 61 6e 73 6c 61 74  ngle.** translat
0220: 69 6f 6e 20 75 6e 69 74 2e 0a 2a 2a 0a 2a 2a 20  ion unit..**.** 
0230: 54 68 69 73 20 66 69 6c 65 20 69 73 20 61 6c 6c  This file is all
0240: 20 79 6f 75 20 6e 65 65 64 20 74 6f 20 63 6f 6d   you need to com
0250: 70 69 6c 65 20 53 51 4c 69 74 65 2e 20 20 54 6f  pile SQLite.  To
0260: 20 75 73 65 20 53 51 4c 69 74 65 20 69 6e 20 6f   use SQLite in o
0270: 74 68 65 72 0a 2a 2a 20 70 72 6f 67 72 61 6d 73  ther.** programs
0280: 2c 20 79 6f 75 20 6e 65 65 64 20 74 68 69 73 20  , you need this 
0290: 66 69 6c 65 20 61 6e 64 20 74 68 65 20 22 73 71  file and the "sq
02a0: 6c 69 74 65 33 2e 68 22 20 68 65 61 64 65 72 20  lite3.h" header 
02b0: 66 69 6c 65 20 74 68 61 74 20 64 65 66 69 6e 65  file that define
02c0: 73 0a 2a 2a 20 74 68 65 20 70 72 6f 67 72 61 6d  s.** the program
02d0: 6d 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 74  ming interface t
02e0: 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  o the SQLite lib
02f0: 72 61 72 79 2e 20 20 28 49 66 20 79 6f 75 20 64  rary.  (If you d
0300: 6f 20 6e 6f 74 20 68 61 76 65 20 0a 2a 2a 20 74  o not have .** t
0310: 68 65 20 22 73 71 6c 69 74 65 33 2e 68 22 20 68  he "sqlite3.h" h
0320: 65 61 64 65 72 20 66 69 6c 65 20 61 74 20 68 61  eader file at ha
0330: 6e 64 2c 20 79 6f 75 20 77 69 6c 6c 20 66 69 6e  nd, you will fin
0340: 64 20 61 20 63 6f 70 79 20 65 6d 62 65 64 64 65  d a copy embedde
0350: 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  d within.** the 
0360: 74 65 78 74 20 6f 66 20 74 68 69 73 20 66 69 6c  text of this fil
0370: 65 2e 20 20 53 65 61 72 63 68 20 66 6f 72 20 22  e.  Search for "
0380: 42 65 67 69 6e 20 66 69 6c 65 20 73 71 6c 69 74  Begin file sqlit
0390: 65 33 2e 68 22 20 74 6f 20 66 69 6e 64 20 74 68  e3.h" to find th
03a0: 65 20 73 74 61 72 74 0a 2a 2a 20 6f 66 20 74 68  e start.** of th
03b0: 65 20 65 6d 62 65 64 64 65 64 20 73 71 6c 69 74  e embedded sqlit
03c0: 65 33 2e 68 20 68 65 61 64 65 72 20 66 69 6c 65  e3.h header file
03d0: 2e 29 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 6f  .) Additional co
03e0: 64 65 20 66 69 6c 65 73 20 6d 61 79 20 62 65 20  de files may be 
03f0: 6e 65 65 64 65 64 0a 2a 2a 20 69 66 20 79 6f 75  needed.** if you
0400: 20 77 61 6e 74 20 61 20 77 72 61 70 70 65 72 20   want a wrapper 
0410: 74 6f 20 69 6e 74 65 72 66 61 63 65 20 53 51 4c  to interface SQL
0420: 69 74 65 20 77 69 74 68 20 79 6f 75 72 20 63 68  ite with your ch
0430: 6f 69 63 65 20 6f 66 20 70 72 6f 67 72 61 6d 6d  oice of programm
0440: 69 6e 67 0a 2a 2a 20 6c 61 6e 67 75 61 67 65 2e  ing.** language.
0450: 20 54 68 65 20 63 6f 64 65 20 66 6f 72 20 74 68   The code for th
0460: 65 20 22 73 71 6c 69 74 65 33 22 20 63 6f 6d 6d  e "sqlite3" comm
0470: 61 6e 64 2d 6c 69 6e 65 20 73 68 65 6c 6c 20 69  and-line shell i
0480: 73 20 61 6c 73 6f 20 69 6e 20 61 0a 2a 2a 20 73  s also in a.** s
0490: 65 70 61 72 61 74 65 20 66 69 6c 65 2e 20 54 68  eparate file. Th
04a0: 69 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73  is file contains
04b0: 20 6f 6e 6c 79 20 63 6f 64 65 20 66 6f 72 20 74   only code for t
04c0: 68 65 20 63 6f 72 65 20 53 51 4c 69 74 65 20 6c  he core SQLite l
04d0: 69 62 72 61 72 79 2e 0a 2a 2f 0a 23 64 65 66 69  ibrary..*/.#defi
04e0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 45 20 31  ne SQLITE_CORE 1
04f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
0500: 41 4d 41 4c 47 41 4d 41 54 49 4f 4e 20 31 0a 23  AMALGAMATION 1.#
0510: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 50 52  ifndef SQLITE_PR
0520: 49 56 41 54 45 0a 23 20 64 65 66 69 6e 65 20 53  IVATE.# define S
0530: 51 4c 49 54 45 5f 50 52 49 56 41 54 45 20 73 74  QLITE_PRIVATE st
0540: 61 74 69 63 0a 23 65 6e 64 69 66 0a 2f 2a 2a 2a  atic.#endif./***
0550: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69  *********** Begi
0560: 6e 20 66 69 6c 65 20 73 71 6c 69 74 65 49 6e 74  n file sqliteInt
0570: 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  .h *************
0580: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0590: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a  **********/./*.*
05a0: 2a 20 32 30 30 31 20 53 65 70 74 65 6d 62 65 72  * 2001 September
05b0: 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75   15.**.** The au
05c0: 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63  thor disclaims c
05d0: 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73  opyright to this
05e0: 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49   source code.  I
05f0: 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20  n place of.** a 
0600: 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65  legal notice, he
0610: 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67  re is a blessing
0620: 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79  :.**.**    May y
0630: 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e  ou do good and n
0640: 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d  ot evil..**    M
0650: 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67  ay you find forg
0660: 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72  iveness for your
0670: 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65  self and forgive
0680: 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d   others..**    M
0690: 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65  ay you share fre
06a0: 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e  ely, never takin
06b0: 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20  g more than you 
06c0: 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a  give..**.*******
06d0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
06e0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
06f0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0700: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0710: 2a 2a 0a 2a 2a 20 49 6e 74 65 72 6e 61 6c 20 69  **.** Internal i
0720: 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 69 74  nterface definit
0730: 69 6f 6e 73 20 66 6f 72 20 53 51 4c 69 74 65 2e  ions for SQLite.
0740: 0a 2a 2a 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f  .**.*/.#ifndef _
0750: 53 51 4c 49 54 45 49 4e 54 5f 48 5f 0a 23 64 65  SQLITEINT_H_.#de
0760: 66 69 6e 65 20 5f 53 51 4c 49 54 45 49 4e 54 5f  fine _SQLITEINT_
0770: 48 5f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73  H_../*.** Make s
0780: 75 72 65 20 74 68 61 74 20 72 61 6e 64 5f 73 28  ure that rand_s(
0790: 29 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 6f  ) is available o
07a0: 6e 20 57 69 6e 64 6f 77 73 20 73 79 73 74 65 6d  n Windows system
07b0: 73 20 77 69 74 68 20 4d 53 56 43 20 32 30 30 35  s with MSVC 2005
07c0: 0a 2a 2a 20 6f 72 20 68 69 67 68 65 72 2e 0a 2a  .** or higher..*
07d0: 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28 5f 4d  /.#if defined(_M
07e0: 53 43 5f 56 45 52 29 20 26 26 20 5f 4d 53 43 5f  SC_VER) && _MSC_
07f0: 56 45 52 3e 3d 31 34 30 30 0a 23 20 20 64 65 66  VER>=1400.#  def
0800: 69 6e 65 20 5f 43 52 54 5f 52 41 4e 44 5f 53 0a  ine _CRT_RAND_S.
0810: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 49 6e  #endif../*.** In
0820: 63 6c 75 64 65 20 74 68 65 20 68 65 61 64 65 72  clude the header
0830: 20 66 69 6c 65 20 75 73 65 64 20 74 6f 20 63 75   file used to cu
0840: 73 74 6f 6d 69 7a 65 20 74 68 65 20 63 6f 6d 70  stomize the comp
0850: 69 6c 65 72 20 6f 70 74 69 6f 6e 73 20 66 6f 72  iler options for
0860: 20 4d 53 56 43 2e 0a 2a 2a 20 54 68 69 73 20 73   MSVC..** This s
0870: 68 6f 75 6c 64 20 62 65 20 64 6f 6e 65 20 66 69  hould be done fi
0880: 72 73 74 20 73 6f 20 74 68 61 74 20 69 74 20 63  rst so that it c
0890: 61 6e 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20  an successfully 
08a0: 70 72 65 76 65 6e 74 20 73 70 75 72 69 6f 75 73  prevent spurious
08b0: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 77 61 72  .** compiler war
08c0: 6e 69 6e 67 73 20 64 75 65 20 74 6f 20 73 75 62  nings due to sub
08d0: 73 65 71 75 65 6e 74 20 63 6f 6e 74 65 6e 74 20  sequent content 
08e0: 69 6e 20 74 68 69 73 20 66 69 6c 65 20 61 6e 64  in this file and
08f0: 20 6f 74 68 65 72 20 66 69 6c 65 73 0a 2a 2a 20   other files.** 
0900: 74 68 61 74 20 61 72 65 20 69 6e 63 6c 75 64 65  that are include
0910: 64 20 62 79 20 74 68 69 73 20 66 69 6c 65 2e 0a  d by this file..
0920: 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */./************
0930: 2a 2a 20 49 6e 63 6c 75 64 65 20 6d 73 76 63 2e  ** Include msvc.
0940: 68 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20  h in the middle 
0950: 6f 66 20 73 71 6c 69 74 65 49 6e 74 2e 68 20 2a  of sqliteInt.h *
0960: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0970: 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */./************
0980: 2a 2a 20 42 65 67 69 6e 20 66 69 6c 65 20 6d 73  ** Begin file ms
0990: 76 63 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  vc.h ***********
09a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
09b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
09c0: 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30 31 35 20 4a 61  */./*.** 2015 Ja
09d0: 6e 75 61 72 79 20 31 32 0a 2a 2a 0a 2a 2a 20 54  nuary 12.**.** T
09e0: 68 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61  he author discla
09f0: 69 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f  ims copyright to
0a00: 20 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64   this source cod
0a10: 65 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a  e.  In place of.
0a20: 2a 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63  ** a legal notic
0a30: 65 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65  e, here is a ble
0a40: 73 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20  ssing:.**.**    
0a50: 4d 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20  May you do good 
0a60: 61 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a  and not evil..**
0a70: 20 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64      May you find
0a80: 20 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72   forgiveness for
0a90: 20 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f   yourself and fo
0aa0: 72 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a  rgive others..**
0ab0: 20 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72      May you shar
0ac0: 65 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20  e freely, never 
0ad0: 74 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e  taking more than
0ae0: 20 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a   you give..**.**
0af0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0b00: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0b10: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0b20: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0b30: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a  ************.**.
0b40: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e  ** This file con
0b50: 74 61 69 6e 73 20 63 6f 64 65 20 74 68 61 74 20  tains code that 
0b60: 69 73 20 73 70 65 63 69 66 69 63 20 74 6f 20 4d  is specific to M
0b70: 53 56 43 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20  SVC..*/.#ifndef 
0b80: 5f 4d 53 56 43 5f 48 5f 0a 23 64 65 66 69 6e 65  _MSVC_H_.#define
0b90: 20 5f 4d 53 56 43 5f 48 5f 0a 0a 23 69 66 20 64   _MSVC_H_..#if d
0ba0: 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29  efined(_MSC_VER)
0bb0: 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67  .#pragma warning
0bc0: 28 64 69 73 61 62 6c 65 20 3a 20 34 30 35 34 29  (disable : 4054)
0bd0: 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67  .#pragma warning
0be0: 28 64 69 73 61 62 6c 65 20 3a 20 34 30 35 35 29  (disable : 4055)
0bf0: 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67  .#pragma warning
0c00: 28 64 69 73 61 62 6c 65 20 3a 20 34 31 30 30 29  (disable : 4100)
0c10: 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67  .#pragma warning
0c20: 28 64 69 73 61 62 6c 65 20 3a 20 34 31 32 37 29  (disable : 4127)
0c30: 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67  .#pragma warning
0c40: 28 64 69 73 61 62 6c 65 20 3a 20 34 31 33 30 29  (disable : 4130)
0c50: 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67  .#pragma warning
0c60: 28 64 69 73 61 62 6c 65 20 3a 20 34 31 35 32 29  (disable : 4152)
0c70: 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67  .#pragma warning
0c80: 28 64 69 73 61 62 6c 65 20 3a 20 34 31 38 39 29  (disable : 4189)
0c90: 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67  .#pragma warning
0ca0: 28 64 69 73 61 62 6c 65 20 3a 20 34 32 30 36 29  (disable : 4206)
0cb0: 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67  .#pragma warning
0cc0: 28 64 69 73 61 62 6c 65 20 3a 20 34 32 31 30 29  (disable : 4210)
0cd0: 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67  .#pragma warning
0ce0: 28 64 69 73 61 62 6c 65 20 3a 20 34 32 33 32 29  (disable : 4232)
0cf0: 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67  .#pragma warning
0d00: 28 64 69 73 61 62 6c 65 20 3a 20 34 32 34 34 29  (disable : 4244)
0d10: 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67  .#pragma warning
0d20: 28 64 69 73 61 62 6c 65 20 3a 20 34 33 30 35 29  (disable : 4305)
0d30: 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67  .#pragma warning
0d40: 28 64 69 73 61 62 6c 65 20 3a 20 34 33 30 36 29  (disable : 4306)
0d50: 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67  .#pragma warning
0d60: 28 64 69 73 61 62 6c 65 20 3a 20 34 37 30 32 29  (disable : 4702)
0d70: 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67  .#pragma warning
0d80: 28 64 69 73 61 62 6c 65 20 3a 20 34 37 30 36 29  (disable : 4706)
0d90: 0a 23 65 6e 64 69 66 20 2f 2a 20 64 65 66 69 6e  .#endif /* defin
0da0: 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 2a 2f 0a  ed(_MSC_VER) */.
0db0: 0a 23 65 6e 64 69 66 20 2f 2a 20 5f 4d 53 56 43  .#endif /* _MSVC
0dc0: 5f 48 5f 20 2a 2f 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a  _H_ */../*******
0dd0: 2a 2a 2a 2a 2a 2a 2a 20 45 6e 64 20 6f 66 20 6d  ******* End of m
0de0: 73 76 63 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  svc.h **********
0df0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e00: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e10: 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a  ******/./*******
0e20: 2a 2a 2a 2a 2a 2a 2a 20 43 6f 6e 74 69 6e 75 69  ******* Continui
0e30: 6e 67 20 77 68 65 72 65 20 77 65 20 6c 65 66 74  ng where we left
0e40: 20 6f 66 66 20 69 6e 20 73 71 6c 69 74 65 49 6e   off in sqliteIn
0e50: 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  t.h ************
0e60: 2a 2a 2a 2a 2a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53  ******/../*.** S
0e70: 70 65 63 69 61 6c 20 73 65 74 75 70 20 66 6f 72  pecial setup for
0e80: 20 56 78 57 6f 72 6b 73 0a 2a 2f 0a 2f 2a 2a 2a   VxWorks.*/./***
0e90: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 49 6e 63 6c  *********** Incl
0ea0: 75 64 65 20 76 78 77 6f 72 6b 73 2e 68 20 69 6e  ude vxworks.h in
0eb0: 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 73   the middle of s
0ec0: 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a  qliteInt.h *****
0ed0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a  **********/./***
0ee0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69  *********** Begi
0ef0: 6e 20 66 69 6c 65 20 76 78 77 6f 72 6b 73 2e 68  n file vxworks.h
0f00: 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   ***************
0f10: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0f20: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a  **********/./*.*
0f30: 2a 20 32 30 31 35 2d 30 33 2d 30 32 0a 2a 2a 0a  * 2015-03-02.**.
0f40: 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 20 64 69  ** The author di
0f50: 73 63 6c 61 69 6d 73 20 63 6f 70 79 72 69 67 68  sclaims copyrigh
0f60: 74 20 74 6f 20 74 68 69 73 20 73 6f 75 72 63 65  t to this source
0f70: 20 63 6f 64 65 2e 20 20 49 6e 20 70 6c 61 63 65   code.  In place
0f80: 20 6f 66 0a 2a 2a 20 61 20 6c 65 67 61 6c 20 6e   of.** a legal n
0f90: 6f 74 69 63 65 2c 20 68 65 72 65 20 69 73 20 61  otice, here is a
0fa0: 20 62 6c 65 73 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a   blessing:.**.**
0fb0: 20 20 20 20 4d 61 79 20 79 6f 75 20 64 6f 20 67      May you do g
0fc0: 6f 6f 64 20 61 6e 64 20 6e 6f 74 20 65 76 69 6c  ood and not evil
0fd0: 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20  ..**    May you 
0fe0: 66 69 6e 64 20 66 6f 72 67 69 76 65 6e 65 73 73  find forgiveness
0ff0: 20 66 6f 72 20 79 6f 75 72 73 65 6c 66 20 61 6e   for yourself an
1000: 64 20 66 6f 72 67 69 76 65 20 6f 74 68 65 72 73  d forgive others
1010: 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20  ..**    May you 
1020: 73 68 61 72 65 20 66 72 65 65 6c 79 2c 20 6e 65  share freely, ne
1030: 76 65 72 20 74 61 6b 69 6e 67 20 6d 6f 72 65 20  ver taking more 
1040: 74 68 61 6e 20 79 6f 75 20 67 69 76 65 2e 0a 2a  than you give..*
1050: 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  *.**************
1060: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1070: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1080: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1090: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
10a0: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65  .**.** This file
10b0: 20 63 6f 6e 74 61 69 6e 73 20 63 6f 64 65 20 74   contains code t
10c0: 68 61 74 20 69 73 20 73 70 65 63 69 66 69 63 20  hat is specific 
10d0: 74 6f 20 57 69 6e 64 20 52 69 76 65 72 27 73 20  to Wind River's 
10e0: 56 78 57 6f 72 6b 73 0a 2a 2f 0a 23 69 66 20 64  VxWorks.*/.#if d
10f0: 65 66 69 6e 65 64 28 5f 5f 52 54 50 5f 5f 29 20  efined(__RTP__) 
1100: 7c 7c 20 64 65 66 69 6e 65 64 28 5f 57 52 53 5f  || defined(_WRS_
1110: 4b 45 52 4e 45 4c 29 0a 2f 2a 20 54 68 69 73 20  KERNEL)./* This 
1120: 69 73 20 56 78 57 6f 72 6b 73 2e 20 20 53 65 74  is VxWorks.  Set
1130: 20 75 70 20 74 68 69 6e 67 73 20 73 70 65 63 69   up things speci
1140: 61 6c 6c 79 20 66 6f 72 20 74 68 61 74 20 4f 53  ally for that OS
1150: 0a 2a 2f 0a 23 69 6e 63 6c 75 64 65 20 3c 76 78  .*/.#include <vx
1160: 57 6f 72 6b 73 2e 68 3e 0a 23 69 6e 63 6c 75 64  Works.h>.#includ
1170: 65 20 3c 70 74 68 72 65 61 64 2e 68 3e 20 20 2f  e <pthread.h>  /
1180: 2a 20 61 6d 61 6c 67 61 6d 61 74 6f 72 3a 20 64  * amalgamator: d
1190: 6f 6e 74 63 61 63 68 65 20 2a 2f 0a 23 64 65 66  ontcache */.#def
11a0: 69 6e 65 20 4f 53 5f 56 58 57 4f 52 4b 53 20 31  ine OS_VXWORKS 1
11b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
11c0: 4f 53 5f 4f 54 48 45 52 20 30 0a 23 64 65 66 69  OS_OTHER 0.#defi
11d0: 6e 65 20 53 51 4c 49 54 45 5f 48 4f 4d 45 47 52  ne SQLITE_HOMEGR
11e0: 4f 57 4e 5f 52 45 43 55 52 53 49 56 45 5f 4d 55  OWN_RECURSIVE_MU
11f0: 54 45 58 20 31 0a 23 64 65 66 69 6e 65 20 53 51  TEX 1.#define SQ
1200: 4c 49 54 45 5f 4f 4d 49 54 5f 4c 4f 41 44 5f 45  LITE_OMIT_LOAD_E
1210: 58 54 45 4e 53 49 4f 4e 20 31 0a 23 64 65 66 69  XTENSION 1.#defi
1220: 6e 65 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  ne SQLITE_ENABLE
1230: 5f 4c 4f 43 4b 49 4e 47 5f 53 54 59 4c 45 20 30  _LOCKING_STYLE 0
1240: 0a 23 64 65 66 69 6e 65 20 48 41 56 45 5f 55 54  .#define HAVE_UT
1250: 49 4d 45 20 31 0a 23 65 6c 73 65 0a 2f 2a 20 54  IME 1.#else./* T
1260: 68 69 73 20 69 73 20 6e 6f 74 20 56 78 57 6f 72  his is not VxWor
1270: 6b 73 2e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 4f  ks. */.#define O
1280: 53 5f 56 58 57 4f 52 4b 53 20 30 0a 23 64 65 66  S_VXWORKS 0.#def
1290: 69 6e 65 20 48 41 56 45 5f 46 43 48 4f 57 4e 20  ine HAVE_FCHOWN 
12a0: 31 0a 23 64 65 66 69 6e 65 20 48 41 56 45 5f 52  1.#define HAVE_R
12b0: 45 41 44 4c 49 4e 4b 20 31 0a 23 64 65 66 69 6e  EADLINK 1.#defin
12c0: 65 20 48 41 56 45 5f 4c 53 54 41 54 20 31 0a 23  e HAVE_LSTAT 1.#
12d0: 65 6e 64 69 66 20 2f 2a 20 64 65 66 69 6e 65 64  endif /* defined
12e0: 28 5f 57 52 53 5f 4b 45 52 4e 45 4c 29 20 2a 2f  (_WRS_KERNEL) */
12f0: 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ../*************
1300: 2a 20 45 6e 64 20 6f 66 20 76 78 77 6f 72 6b 73  * End of vxworks
1310: 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  .h *************
1320: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1330: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1340: 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /./*************
1350: 2a 20 43 6f 6e 74 69 6e 75 69 6e 67 20 77 68 65  * Continuing whe
1360: 72 65 20 77 65 20 6c 65 66 74 20 6f 66 66 20 69  re we left off i
1370: 6e 20 73 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a  n sqliteInt.h **
1380: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1390: 2f 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 23  /../*.** These #
13a0: 64 65 66 69 6e 65 73 20 73 68 6f 75 6c 64 20 65  defines should e
13b0: 6e 61 62 6c 65 20 3e 32 47 42 20 66 69 6c 65 20  nable >2GB file 
13c0: 73 75 70 70 6f 72 74 20 6f 6e 20 50 4f 53 49 58  support on POSIX
13d0: 20 69 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72   if the.** under
13e0: 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20  lying operating 
13f0: 73 79 73 74 65 6d 20 73 75 70 70 6f 72 74 73 20  system supports 
1400: 69 74 2e 20 20 49 66 20 74 68 65 20 4f 53 20 6c  it.  If the OS l
1410: 61 63 6b 73 0a 2a 2a 20 6c 61 72 67 65 20 66 69  acks.** large fi
1420: 6c 65 20 73 75 70 70 6f 72 74 2c 20 6f 72 20 69  le support, or i
1430: 66 20 74 68 65 20 4f 53 20 69 73 20 77 69 6e 64  f the OS is wind
1440: 6f 77 73 2c 20 74 68 65 73 65 20 73 68 6f 75 6c  ows, these shoul
1450: 64 20 62 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a  d be no-ops..**.
1460: 2a 2a 20 54 69 63 6b 65 74 20 23 32 37 33 39 3a  ** Ticket #2739:
1470: 20 20 54 68 65 20 5f 4c 41 52 47 45 46 49 4c 45    The _LARGEFILE
1480: 5f 53 4f 55 52 43 45 20 6d 61 63 72 6f 20 6d 75  _SOURCE macro mu
1490: 73 74 20 61 70 70 65 61 72 20 62 65 66 6f 72 65  st appear before
14a0: 20 61 6e 79 0a 2a 2a 20 73 79 73 74 65 6d 20 23   any.** system #
14b0: 69 6e 63 6c 75 64 65 73 2e 20 20 48 65 6e 63 65  includes.  Hence
14c0: 2c 20 74 68 69 73 20 62 6c 6f 63 6b 20 6f 66 20  , this block of 
14d0: 63 6f 64 65 20 6d 75 73 74 20 62 65 20 74 68 65  code must be the
14e0: 20 76 65 72 79 20 66 69 72 73 74 0a 2a 2a 20 63   very first.** c
14f0: 6f 64 65 20 69 6e 20 61 6c 6c 20 73 6f 75 72 63  ode in all sourc
1500: 65 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 4c  e files..**.** L
1510: 61 72 67 65 20 66 69 6c 65 20 73 75 70 70 6f 72  arge file suppor
1520: 74 20 63 61 6e 20 62 65 20 64 69 73 61 62 6c 65  t can be disable
1530: 64 20 75 73 69 6e 67 20 74 68 65 20 2d 44 53 51  d using the -DSQ
1540: 4c 49 54 45 5f 44 49 53 41 42 4c 45 5f 4c 46 53  LITE_DISABLE_LFS
1550: 20 73 77 69 74 63 68 0a 2a 2a 20 6f 6e 20 74 68   switch.** on th
1560: 65 20 63 6f 6d 70 69 6c 65 72 20 63 6f 6d 6d 61  e compiler comma
1570: 6e 64 20 6c 69 6e 65 2e 20 20 54 68 69 73 20 69  nd line.  This i
1580: 73 20 6e 65 63 65 73 73 61 72 79 20 69 66 20 79  s necessary if y
1590: 6f 75 20 61 72 65 20 63 6f 6d 70 69 6c 69 6e 67  ou are compiling
15a0: 0a 2a 2a 20 6f 6e 20 61 20 72 65 63 65 6e 74 20  .** on a recent 
15b0: 6d 61 63 68 69 6e 65 20 28 65 78 3a 20 52 65 64  machine (ex: Red
15c0: 20 48 61 74 20 37 2e 32 29 20 62 75 74 20 79 6f   Hat 7.2) but yo
15d0: 75 20 77 61 6e 74 20 79 6f 75 72 20 63 6f 64 65  u want your code
15e0: 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 6f 6e 20 61   to work.** on a
15f0: 6e 20 6f 6c 64 65 72 20 6d 61 63 68 69 6e 65 20  n older machine 
1600: 28 65 78 3a 20 52 65 64 20 48 61 74 20 36 2e 30  (ex: Red Hat 6.0
1610: 29 2e 20 20 49 66 20 79 6f 75 20 63 6f 6d 70 69  ).  If you compi
1620: 6c 65 20 6f 6e 20 52 65 64 20 48 61 74 20 37 2e  le on Red Hat 7.
1630: 32 0a 2a 2a 20 77 69 74 68 6f 75 74 20 74 68 69  2.** without thi
1640: 73 20 6f 70 74 69 6f 6e 2c 20 4c 46 53 20 69 73  s option, LFS is
1650: 20 65 6e 61 62 6c 65 2e 20 20 42 75 74 20 4c 46   enable.  But LF
1660: 53 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74  S does not exist
1670: 20 69 6e 20 74 68 65 20 6b 65 72 6e 65 6c 0a 2a   in the kernel.*
1680: 2a 20 69 6e 20 52 65 64 20 48 61 74 20 36 2e 30  * in Red Hat 6.0
1690: 2c 20 73 6f 20 74 68 65 20 63 6f 64 65 20 77 6f  , so the code wo
16a0: 6e 27 74 20 77 6f 72 6b 2e 20 20 48 65 6e 63 65  n't work.  Hence
16b0: 2c 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 62 69  , for maximum bi
16c0: 6e 61 72 79 0a 2a 2a 20 70 6f 72 74 61 62 69 6c  nary.** portabil
16d0: 69 74 79 20 79 6f 75 20 73 68 6f 75 6c 64 20 6f  ity you should o
16e0: 6d 69 74 20 4c 46 53 2e 0a 2a 2a 0a 2a 2a 20 54  mit LFS..**.** T
16f0: 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61  he previous para
1700: 67 72 61 70 68 20 77 61 73 20 77 72 69 74 74 65  graph was writte
1710: 6e 20 69 6e 20 32 30 30 35 2e 20 20 28 54 68 69  n in 2005.  (Thi
1720: 73 20 70 61 72 61 67 72 61 70 68 20 69 73 20 77  s paragraph is w
1730: 72 69 74 74 65 6e 0a 2a 2a 20 6f 6e 20 32 30 30  ritten.** on 200
1740: 38 2d 31 31 2d 32 38 2e 29 20 54 68 65 73 65 20  8-11-28.) These 
1750: 64 61 79 73 2c 20 61 6c 6c 20 4c 69 6e 75 78 20  days, all Linux 
1760: 6b 65 72 6e 65 6c 73 20 73 75 70 70 6f 72 74 20  kernels support 
1770: 6c 61 72 67 65 20 66 69 6c 65 73 2c 20 73 6f 0a  large files, so.
1780: 2a 2a 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72  ** you should pr
1790: 6f 62 61 62 6c 79 20 6c 65 61 76 65 20 4c 46 53  obably leave LFS
17a0: 20 65 6e 61 62 6c 65 64 2e 20 20 42 75 74 20 73   enabled.  But s
17b0: 6f 6d 65 20 65 6d 62 65 64 64 65 64 20 70 6c 61  ome embedded pla
17c0: 74 66 6f 72 6d 73 20 6d 69 67 68 74 0a 2a 2a 20  tforms might.** 
17d0: 6c 61 63 6b 20 4c 46 53 20 69 6e 20 77 68 69 63  lack LFS in whic
17e0: 68 20 63 61 73 65 20 74 68 65 20 53 51 4c 49 54  h case the SQLIT
17f0: 45 5f 44 49 53 41 42 4c 45 5f 4c 46 53 20 6d 61  E_DISABLE_LFS ma
1800: 63 72 6f 20 6d 69 67 68 74 20 73 74 69 6c 6c 20  cro might still 
1810: 62 65 20 75 73 65 66 75 6c 2e 0a 2a 2a 0a 2a 2a  be useful..**.**
1820: 20 53 69 6d 69 6c 61 72 20 69 73 20 74 72 75 65   Similar is true
1830: 20 66 6f 72 20 4d 61 63 20 4f 53 20 58 2e 20 20   for Mac OS X.  
1840: 4c 46 53 20 69 73 20 6f 6e 6c 79 20 73 75 70 70  LFS is only supp
1850: 6f 72 74 65 64 20 6f 6e 20 4d 61 63 20 4f 53 20  orted on Mac OS 
1860: 58 20 39 20 61 6e 64 20 6c 61 74 65 72 2e 0a 2a  X 9 and later..*
1870: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
1880: 5f 44 49 53 41 42 4c 45 5f 4c 46 53 0a 23 20 64  _DISABLE_LFS.# d
1890: 65 66 69 6e 65 20 5f 4c 41 52 47 45 5f 46 49 4c  efine _LARGE_FIL
18a0: 45 20 20 20 20 20 20 20 31 0a 23 20 69 66 6e 64  E       1.# ifnd
18b0: 65 66 20 5f 46 49 4c 45 5f 4f 46 46 53 45 54 5f  ef _FILE_OFFSET_
18c0: 42 49 54 53 0a 23 20 20 20 64 65 66 69 6e 65 20  BITS.#   define 
18d0: 5f 46 49 4c 45 5f 4f 46 46 53 45 54 5f 42 49 54  _FILE_OFFSET_BIT
18e0: 53 20 36 34 0a 23 20 65 6e 64 69 66 0a 23 20 64  S 64.# endif.# d
18f0: 65 66 69 6e 65 20 5f 4c 41 52 47 45 46 49 4c 45  efine _LARGEFILE
1900: 5f 53 4f 55 52 43 45 20 31 0a 23 65 6e 64 69 66  _SOURCE 1.#endif
1910: 0a 0a 2f 2a 20 57 68 61 74 20 76 65 72 73 69 6f  ../* What versio
1920: 6e 20 6f 66 20 47 43 43 20 69 73 20 62 65 69 6e  n of GCC is bein
1930: 67 20 75 73 65 64 2e 20 20 30 20 6d 65 61 6e 73  g used.  0 means
1940: 20 47 43 43 20 69 73 20 6e 6f 74 20 62 65 69 6e   GCC is not bein
1950: 67 20 75 73 65 64 20 2a 2f 0a 23 69 66 64 65 66  g used */.#ifdef
1960: 20 5f 5f 47 4e 55 43 5f 5f 0a 23 20 64 65 66 69   __GNUC__.# defi
1970: 6e 65 20 47 43 43 5f 56 45 52 53 49 4f 4e 20 28  ne GCC_VERSION (
1980: 5f 5f 47 4e 55 43 5f 5f 2a 31 30 30 30 30 30 30  __GNUC__*1000000
1990: 2b 5f 5f 47 4e 55 43 5f 4d 49 4e 4f 52 5f 5f 2a  +__GNUC_MINOR__*
19a0: 31 30 30 30 2b 5f 5f 47 4e 55 43 5f 50 41 54 43  1000+__GNUC_PATC
19b0: 48 4c 45 56 45 4c 5f 5f 29 0a 23 65 6c 73 65 0a  HLEVEL__).#else.
19c0: 23 20 64 65 66 69 6e 65 20 47 43 43 5f 56 45 52  # define GCC_VER
19d0: 53 49 4f 4e 20 30 0a 23 65 6e 64 69 66 0a 0a 2f  SION 0.#endif../
19e0: 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 76 61 72  * Needed for var
19f0: 69 6f 75 73 20 64 65 66 69 6e 69 74 69 6f 6e 73  ious definitions
1a00: 2e 2e 2e 20 2a 2f 0a 23 69 66 20 64 65 66 69 6e  ... */.#if defin
1a10: 65 64 28 5f 5f 47 4e 55 43 5f 5f 29 20 26 26 20  ed(__GNUC__) && 
1a20: 21 64 65 66 69 6e 65 64 28 5f 47 4e 55 5f 53 4f  !defined(_GNU_SO
1a30: 55 52 43 45 29 0a 23 20 64 65 66 69 6e 65 20 5f  URCE).# define _
1a40: 47 4e 55 5f 53 4f 55 52 43 45 0a 23 65 6e 64 69  GNU_SOURCE.#endi
1a50: 66 0a 0a 23 69 66 20 64 65 66 69 6e 65 64 28 5f  f..#if defined(_
1a60: 5f 4f 70 65 6e 42 53 44 5f 5f 29 20 26 26 20 21  _OpenBSD__) && !
1a70: 64 65 66 69 6e 65 64 28 5f 42 53 44 5f 53 4f 55  defined(_BSD_SOU
1a80: 52 43 45 29 0a 23 20 64 65 66 69 6e 65 20 5f 42  RCE).# define _B
1a90: 53 44 5f 53 4f 55 52 43 45 0a 23 65 6e 64 69 66  SD_SOURCE.#endif
1aa0: 0a 0a 2f 2a 0a 2a 2a 20 46 6f 72 20 4d 69 6e 47  ../*.** For MinG
1ab0: 57 2c 20 63 68 65 63 6b 20 74 6f 20 73 65 65 20  W, check to see 
1ac0: 69 66 20 77 65 20 63 61 6e 20 69 6e 63 6c 75 64  if we can includ
1ad0: 65 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c  e the header fil
1ae0: 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 74 73  e containing its
1af0: 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 69 6e 66 6f  .** version info
1b00: 72 6d 61 74 69 6f 6e 2c 20 61 6d 6f 6e 67 20 6f  rmation, among o
1b10: 74 68 65 72 20 74 68 69 6e 67 73 2e 20 20 4e 6f  ther things.  No
1b20: 72 6d 61 6c 6c 79 2c 20 74 68 69 73 20 69 6e 74  rmally, this int
1b30: 65 72 6e 61 6c 20 4d 69 6e 47 57 0a 2a 2a 20 68  ernal MinGW.** h
1b40: 65 61 64 65 72 20 66 69 6c 65 20 77 6f 75 6c 64  eader file would
1b50: 20 5b 6f 6e 6c 79 5d 20 62 65 20 69 6e 63 6c 75   [only] be inclu
1b60: 64 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ded automaticall
1b70: 79 20 62 79 20 6f 74 68 65 72 20 4d 69 6e 47 57  y by other MinGW
1b80: 20 68 65 61 64 65 72 0a 2a 2a 20 66 69 6c 65 73   header.** files
1b90: 3b 20 68 6f 77 65 76 65 72 2c 20 74 68 65 20 63  ; however, the c
1ba0: 6f 6e 74 61 69 6e 65 64 20 76 65 72 73 69 6f 6e  ontained version
1bb0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
1bc0: 6e 6f 77 20 72 65 71 75 69 72 65 64 20 62 79 20  now required by 
1bd0: 74 68 69 73 0a 2a 2a 20 68 65 61 64 65 72 20 66  this.** header f
1be0: 69 6c 65 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75  ile to work arou
1bf0: 6e 64 20 62 69 6e 61 72 79 20 63 6f 6d 70 61 74  nd binary compat
1c00: 69 62 69 6c 69 74 79 20 69 73 73 75 65 73 20 28  ibility issues (
1c10: 73 65 65 20 62 65 6c 6f 77 29 20 61 6e 64 0a 2a  see below) and.*
1c20: 2a 20 74 68 69 73 20 69 73 20 74 68 65 20 6f 6e  * this is the on
1c30: 6c 79 20 6b 6e 6f 77 6e 20 77 61 79 20 74 6f 20  ly known way to 
1c40: 72 65 6c 69 61 62 6c 79 20 6f 62 74 61 69 6e 20  reliably obtain 
1c50: 69 74 2e 20 20 54 68 69 73 20 65 6e 74 69 72 65  it.  This entire
1c60: 20 23 69 66 20 62 6c 6f 63 6b 0a 2a 2a 20 77 6f   #if block.** wo
1c70: 75 6c 64 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c  uld be completel
1c80: 79 20 75 6e 6e 65 63 65 73 73 61 72 79 20 69 66  y unnecessary if
1c90: 20 74 68 65 72 65 20 77 61 73 20 61 6e 79 20 6f   there was any o
1ca0: 74 68 65 72 20 77 61 79 20 6f 66 20 64 65 74 65  ther way of dete
1cb0: 63 74 69 6e 67 0a 2a 2a 20 4d 69 6e 47 57 20 76  cting.** MinGW v
1cc0: 69 61 20 74 68 65 69 72 20 70 72 65 70 72 6f 63  ia their preproc
1cd0: 65 73 73 6f 72 20 28 65 2e 67 2e 20 69 66 20 74  essor (e.g. if t
1ce0: 68 65 79 20 63 75 73 74 6f 6d 69 7a 65 64 20 74  hey customized t
1cf0: 68 65 69 72 20 47 43 43 20 74 6f 20 64 65 66 69  heir GCC to defi
1d00: 6e 65 0a 2a 2a 20 73 6f 6d 65 20 4d 69 6e 47 57  ne.** some MinGW
1d10: 2d 73 70 65 63 69 66 69 63 20 6d 61 63 72 6f 73  -specific macros
1d20: 29 2e 20 20 57 68 65 6e 20 63 6f 6d 70 69 6c 69  ).  When compili
1d30: 6e 67 20 66 6f 72 20 4d 69 6e 47 57 2c 20 65 69  ng for MinGW, ei
1d40: 74 68 65 72 20 74 68 65 0a 2a 2a 20 5f 48 41 56  ther the.** _HAV
1d50: 45 5f 4d 49 4e 47 57 5f 48 20 6f 72 20 5f 48 41  E_MINGW_H or _HA
1d60: 56 45 5f 5f 4d 49 4e 47 57 5f 48 20 28 6e 6f 74  VE__MINGW_H (not
1d70: 65 20 74 68 65 20 65 78 74 72 61 20 75 6e 64 65  e the extra unde
1d80: 72 73 63 6f 72 65 29 20 6d 61 63 72 6f 20 6d 75  rscore) macro mu
1d90: 73 74 20 62 65 0a 2a 2a 20 64 65 66 69 6e 65 64  st be.** defined
1da0: 3b 20 6f 74 68 65 72 77 69 73 65 2c 20 64 65 74  ; otherwise, det
1db0: 65 63 74 69 6f 6e 20 6f 66 20 63 6f 6e 64 69 74  ection of condit
1dc0: 69 6f 6e 73 20 73 70 65 63 69 66 69 63 20 74 6f  ions specific to
1dd0: 20 4d 69 6e 47 57 20 77 69 6c 6c 20 62 65 0a 2a   MinGW will be.*
1de0: 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2f 0a 23  * disabled..*/.#
1df0: 69 66 20 64 65 66 69 6e 65 64 28 5f 48 41 56 45  if defined(_HAVE
1e00: 5f 4d 49 4e 47 57 5f 48 29 0a 23 20 69 6e 63 6c  _MINGW_H).# incl
1e10: 75 64 65 20 22 6d 69 6e 67 77 2e 68 22 0a 23 65  ude "mingw.h".#e
1e20: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 48 41 56  lif defined(_HAV
1e30: 45 5f 5f 4d 49 4e 47 57 5f 48 29 0a 23 20 69 6e  E__MINGW_H).# in
1e40: 63 6c 75 64 65 20 22 5f 6d 69 6e 67 77 2e 68 22  clude "_mingw.h"
1e50: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 46  .#endif../*.** F
1e60: 6f 72 20 4d 69 6e 47 57 20 76 65 72 73 69 6f 6e  or MinGW version
1e70: 20 34 2e 78 20 28 61 6e 64 20 68 69 67 68 65 72   4.x (and higher
1e80: 29 2c 20 63 68 65 63 6b 20 74 6f 20 73 65 65 20  ), check to see 
1e90: 69 66 20 74 68 65 20 5f 55 53 45 5f 33 32 42 49  if the _USE_32BI
1ea0: 54 5f 54 49 4d 45 5f 54 0a 2a 2a 20 64 65 66 69  T_TIME_T.** defi
1eb0: 6e 65 20 69 73 20 72 65 71 75 69 72 65 64 20 74  ne is required t
1ec0: 6f 20 6d 61 69 6e 74 61 69 6e 20 62 69 6e 61 72  o maintain binar
1ed0: 79 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  y compatibility 
1ee0: 77 69 74 68 20 74 68 65 20 4d 53 56 43 20 72 75  with the MSVC ru
1ef0: 6e 74 69 6d 65 0a 2a 2a 20 6c 69 62 72 61 72 79  ntime.** library
1f00: 20 69 6e 20 75 73 65 20 28 65 2e 67 2e 20 66 6f   in use (e.g. fo
1f10: 72 20 57 69 6e 64 6f 77 73 20 58 50 29 2e 0a 2a  r Windows XP)..*
1f20: 2f 0a 23 69 66 20 21 64 65 66 69 6e 65 64 28 5f  /.#if !defined(_
1f30: 55 53 45 5f 33 32 42 49 54 5f 54 49 4d 45 5f 54  USE_32BIT_TIME_T
1f40: 29 20 26 26 20 21 64 65 66 69 6e 65 64 28 5f 55  ) && !defined(_U
1f50: 53 45 5f 36 34 42 49 54 5f 54 49 4d 45 5f 54 29  SE_64BIT_TIME_T)
1f60: 20 26 26 20 5c 0a 20 20 20 20 64 65 66 69 6e 65   && \.    define
1f70: 64 28 5f 57 49 4e 33 32 29 20 26 26 20 21 64 65  d(_WIN32) && !de
1f80: 66 69 6e 65 64 28 5f 57 49 4e 36 34 29 20 26 26  fined(_WIN64) &&
1f90: 20 5c 0a 20 20 20 20 64 65 66 69 6e 65 64 28 5f   \.    defined(_
1fa0: 5f 4d 49 4e 47 57 5f 4d 41 4a 4f 52 5f 56 45 52  _MINGW_MAJOR_VER
1fb0: 53 49 4f 4e 29 20 26 26 20 5f 5f 4d 49 4e 47 57  SION) && __MINGW
1fc0: 5f 4d 41 4a 4f 52 5f 56 45 52 53 49 4f 4e 20 3e  _MAJOR_VERSION >
1fd0: 3d 20 34 20 26 26 20 5c 0a 20 20 20 20 64 65 66  = 4 && \.    def
1fe0: 69 6e 65 64 28 5f 5f 4d 53 56 43 52 54 5f 5f 29  ined(__MSVCRT__)
1ff0: 0a 23 20 64 65 66 69 6e 65 20 5f 55 53 45 5f 33  .# define _USE_3
2000: 32 42 49 54 5f 54 49 4d 45 5f 54 0a 23 65 6e 64  2BIT_TIME_T.#end
2010: 69 66 0a 0a 2f 2a 20 54 68 65 20 70 75 62 6c 69  if../* The publi
2020: 63 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  c SQLite interfa
2030: 63 65 2e 20 20 54 68 65 20 5f 46 49 4c 45 5f 4f  ce.  The _FILE_O
2040: 46 46 53 45 54 5f 42 49 54 53 20 6d 61 63 72 6f  FFSET_BITS macro
2050: 20 6d 75 73 74 20 61 70 70 65 61 72 0a 2a 2a 20   must appear.** 
2060: 66 69 72 73 74 20 69 6e 20 51 4e 58 2e 20 20 41  first in QNX.  A
2070: 6c 73 6f 2c 20 74 68 65 20 5f 55 53 45 5f 33 32  lso, the _USE_32
2080: 42 49 54 5f 54 49 4d 45 5f 54 20 6d 61 63 72 6f  BIT_TIME_T macro
2090: 20 6d 75 73 74 20 61 70 70 65 61 72 20 66 69 72   must appear fir
20a0: 73 74 20 66 6f 72 0a 2a 2a 20 4d 69 6e 47 57 2e  st for.** MinGW.
20b0: 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  .*/./***********
20c0: 2a 2a 2a 20 49 6e 63 6c 75 64 65 20 73 71 6c 69  *** Include sqli
20d0: 74 65 33 2e 68 20 69 6e 20 74 68 65 20 6d 69 64  te3.h in the mid
20e0: 64 6c 65 20 6f 66 20 73 71 6c 69 74 65 49 6e 74  dle of sqliteInt
20f0: 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  .h *************
2100: 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  **/./***********
2110: 2a 2a 2a 20 42 65 67 69 6e 20 66 69 6c 65 20 73  *** Begin file s
2120: 71 6c 69 74 65 33 2e 68 20 2a 2a 2a 2a 2a 2a 2a  qlite3.h *******
2130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2150: 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30 30 31 20 53  **/./*.** 2001 S
2160: 65 70 74 65 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a  eptember 15.**.*
2170: 2a 20 54 68 65 20 61 75 74 68 6f 72 20 64 69 73  * The author dis
2180: 63 6c 61 69 6d 73 20 63 6f 70 79 72 69 67 68 74  claims copyright
2190: 20 74 6f 20 74 68 69 73 20 73 6f 75 72 63 65 20   to this source 
21a0: 63 6f 64 65 2e 20 20 49 6e 20 70 6c 61 63 65 20  code.  In place 
21b0: 6f 66 0a 2a 2a 20 61 20 6c 65 67 61 6c 20 6e 6f  of.** a legal no
21c0: 74 69 63 65 2c 20 68 65 72 65 20 69 73 20 61 20  tice, here is a 
21d0: 62 6c 65 73 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20  blessing:.**.** 
21e0: 20 20 20 4d 61 79 20 79 6f 75 20 64 6f 20 67 6f     May you do go
21f0: 6f 64 20 61 6e 64 20 6e 6f 74 20 65 76 69 6c 2e  od and not evil.
2200: 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 66  .**    May you f
2210: 69 6e 64 20 66 6f 72 67 69 76 65 6e 65 73 73 20  ind forgiveness 
2220: 66 6f 72 20 79 6f 75 72 73 65 6c 66 20 61 6e 64  for yourself and
2230: 20 66 6f 72 67 69 76 65 20 6f 74 68 65 72 73 2e   forgive others.
2240: 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 73  .**    May you s
2250: 68 61 72 65 20 66 72 65 65 6c 79 2c 20 6e 65 76  hare freely, nev
2260: 65 72 20 74 61 6b 69 6e 67 20 6d 6f 72 65 20 74  er taking more t
2270: 68 61 6e 20 79 6f 75 20 67 69 76 65 2e 0a 2a 2a  han you give..**
2280: 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  .***************
2290: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22c0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68  **********.** Th
22d0: 69 73 20 68 65 61 64 65 72 20 66 69 6c 65 20 64  is header file d
22e0: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
22f0: 66 61 63 65 20 74 68 61 74 20 74 68 65 20 53 51  face that the SQ
2300: 4c 69 74 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20  Lite library.** 
2310: 70 72 65 73 65 6e 74 73 20 74 6f 20 63 6c 69 65  presents to clie
2320: 6e 74 20 70 72 6f 67 72 61 6d 73 2e 20 20 49 66  nt programs.  If
2330: 20 61 20 43 2d 66 75 6e 63 74 69 6f 6e 2c 20 73   a C-function, s
2340: 74 72 75 63 74 75 72 65 2c 20 64 61 74 61 74 79  tructure, dataty
2350: 70 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6e 73 74 61  pe,.** or consta
2360: 6e 74 20 64 65 66 69 6e 69 74 69 6f 6e 20 64 6f  nt definition do
2370: 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 69 6e  es not appear in
2380: 20 74 68 69 73 20 66 69 6c 65 2c 20 74 68 65 6e   this file, then
2390: 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 61 20   it is.** not a 
23a0: 70 75 62 6c 69 73 68 65 64 20 41 50 49 20 6f 66  published API of
23b0: 20 53 51 4c 69 74 65 2c 20 69 73 20 73 75 62 6a   SQLite, is subj
23c0: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69  ect to change wi
23d0: 74 68 6f 75 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c  thout.** notice,
23e0: 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20   and should not 
23f0: 62 65 20 72 65 66 65 72 65 6e 63 65 64 20 62 79  be referenced by
2400: 20 70 72 6f 67 72 61 6d 73 20 74 68 61 74 20 75   programs that u
2410: 73 65 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  se SQLite..**.**
2420: 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 64 65 66   Some of the def
2430: 69 6e 69 74 69 6f 6e 73 20 74 68 61 74 20 61 72  initions that ar
2440: 65 20 69 6e 20 74 68 69 73 20 66 69 6c 65 20 61  e in this file a
2450: 72 65 20 6d 61 72 6b 65 64 20 61 73 0a 2a 2a 20  re marked as.** 
2460: 22 65 78 70 65 72 69 6d 65 6e 74 61 6c 22 2e 20  "experimental". 
2470: 20 45 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e   Experimental in
2480: 74 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f 72  terfaces are nor
2490: 6d 61 6c 6c 79 20 6e 65 77 0a 2a 2a 20 66 65 61  mally new.** fea
24a0: 74 75 72 65 73 20 72 65 63 65 6e 74 6c 79 20 61  tures recently a
24b0: 64 64 65 64 20 74 6f 20 53 51 4c 69 74 65 2e 20  dded to SQLite. 
24c0: 20 57 65 20 64 6f 20 6e 6f 74 20 61 6e 74 69 63   We do not antic
24d0: 69 70 61 74 65 20 63 68 61 6e 67 65 73 0a 2a 2a  ipate changes.**
24e0: 20 74 6f 20 65 78 70 65 72 69 6d 65 6e 74 61 6c   to experimental
24f0: 20 69 6e 74 65 72 66 61 63 65 73 20 62 75 74 20   interfaces but 
2500: 72 65 73 65 72 76 65 20 74 68 65 20 72 69 67 68  reserve the righ
2510: 74 20 74 6f 20 6d 61 6b 65 20 6d 69 6e 6f 72 20  t to make minor 
2520: 63 68 61 6e 67 65 73 0a 2a 2a 20 69 66 20 65 78  changes.** if ex
2530: 70 65 72 69 65 6e 63 65 20 66 72 6f 6d 20 75 73  perience from us
2540: 65 20 22 69 6e 20 74 68 65 20 77 69 6c 64 22 20  e "in the wild" 
2550: 73 75 67 67 65 73 74 20 73 75 63 68 20 63 68 61  suggest such cha
2560: 6e 67 65 73 20 61 72 65 20 70 72 75 64 65 6e 74  nges are prudent
2570: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 66 66 69  ..**.** The offi
2580: 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61 67 65 20  cial C-language 
2590: 41 50 49 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  API documentatio
25a0: 6e 20 66 6f 72 20 53 51 4c 69 74 65 20 69 73 20  n for SQLite is 
25b0: 64 65 72 69 76 65 64 0a 2a 2a 20 66 72 6f 6d 20  derived.** from 
25c0: 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74 68 69 73  comments in this
25d0: 20 66 69 6c 65 2e 20 20 54 68 69 73 20 66 69 6c   file.  This fil
25e0: 65 20 69 73 20 74 68 65 20 61 75 74 68 6f 72 69  e is the authori
25f0: 74 61 74 69 76 65 20 73 6f 75 72 63 65 0a 2a 2a  tative source.**
2600: 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74 65 20 69   on how SQLite i
2610: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 73 75  nterfaces are su
2620: 70 70 6f 73 65 64 20 74 6f 20 6f 70 65 72 61 74  pposed to operat
2630: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d  e..**.** The nam
2640: 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20 75  e of this file u
2650: 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  nder configurati
2660: 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 69 73  on management is
2670: 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a   "sqlite.h.in"..
2680: 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c 65 20  ** The makefile 
2690: 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e 6f 72  makes some minor
26a0: 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 69 73   changes to this
26b0: 20 66 69 6c 65 20 28 73 75 63 68 20 61 73 20 69   file (such as i
26c0: 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68 65 20  nserting.** the 
26d0: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 29 20  version number) 
26e0: 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74 73 20  and changes its 
26f0: 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74 65 33  name to "sqlite3
2700: 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f  .h" as.** part o
2710: 66 20 74 68 65 20 62 75 69 6c 64 20 70 72 6f 63  f the build proc
2720: 65 73 73 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20  ess..*/.#ifndef 
2730: 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23 64 65 66  _SQLITE3_H_.#def
2740: 69 6e 65 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a  ine _SQLITE3_H_.
2750: 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72 67  #include <stdarg
2760: 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64 65  .h>     /* Neede
2770: 64 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e 69  d for the defini
2780: 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74 20  tion of va_list 
2790: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73  */../*.** Make s
27a0: 75 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c 20  ure we can call 
27b0: 74 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d 20  this stuff from 
27c0: 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 20 30 0a 65 78  C++..*/.#if 0.ex
27d0: 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69  tern "C" {.#endi
27e0: 66 0a 0a 0a 2f 2a 0a 2a 2a 20 50 72 6f 76 69 64  f.../*.** Provid
27f0: 65 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f  e the ability to
2800: 20 6f 76 65 72 72 69 64 65 20 6c 69 6e 6b 61 67   override linkag
2810: 65 20 66 65 61 74 75 72 65 73 20 6f 66 20 74 68  e features of th
2820: 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a  e interface..*/.
2830: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 45  #ifndef SQLITE_E
2840: 58 54 45 52 4e 0a 23 20 64 65 66 69 6e 65 20 53  XTERN.# define S
2850: 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 65 78 74  QLITE_EXTERN ext
2860: 65 72 6e 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64  ern.#endif.#ifnd
2870: 65 66 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 20  ef SQLITE_API.# 
2880: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 50  define SQLITE_AP
2890: 49 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  I.#endif.#ifndef
28a0: 20 53 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 20   SQLITE_CDECL.# 
28b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 44  define SQLITE_CD
28c0: 45 43 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64  ECL.#endif.#ifnd
28d0: 65 66 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  ef SQLITE_STDCAL
28e0: 4c 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  L.# define SQLIT
28f0: 45 5f 53 54 44 43 41 4c 4c 0a 23 65 6e 64 69 66  E_STDCALL.#endif
2900: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f  ../*.** These no
2910: 2d 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20 75  -op macros are u
2920: 73 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20  sed in front of 
2930: 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d 61  interfaces to ma
2940: 72 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65  rk those.** inte
2950: 72 66 61 63 65 73 20 61 73 20 65 69 74 68 65 72  rfaces as either
2960: 20 64 65 70 72 65 63 61 74 65 64 20 6f 72 20 65   deprecated or e
2970: 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65  xperimental.  Ne
2980: 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  w applications.*
2990: 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65  * should not use
29a0: 20 64 65 70 72 65 63 61 74 65 64 20 69 6e 74 65   deprecated inte
29b0: 72 66 61 63 65 73 20 2d 20 74 68 65 79 20 61 72  rfaces - they ar
29c0: 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20  e supported for 
29d0: 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d  backwards.** com
29e0: 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e  patibility only.
29f0: 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 77 72    Application wr
2a00: 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20  iters should be 
2a10: 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 65 78  aware that.** ex
2a20: 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72  perimental inter
2a30: 66 61 63 65 73 20 61 72 65 20 73 75 62 6a 65 63  faces are subjec
2a40: 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 70  t to change in p
2a50: 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a  oint releases..*
2a60: 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f  *.** These macro
2a70: 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f 6c 76  s used to resolv
2a80: 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e  e to various kin
2a90: 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d  ds of compiler m
2aa0: 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75  agic that.** wou
2ab0: 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61 72 6e  ld generate warn
2ac0: 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77 68 65  ing messages whe
2ad0: 6e 20 74 68 65 79 20 77 65 72 65 20 75 73 65 64  n they were used
2ae0: 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a 20 63  .  But that.** c
2af0: 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 65 6e  ompiler magic en
2b00: 64 65 64 20 75 70 20 67 65 6e 65 72 61 74 69 6e  ded up generatin
2b10: 67 20 73 75 63 68 20 61 20 66 6c 75 72 72 79 20  g such a flurry 
2b20: 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73 0a 2a  of bug reports.*
2b30: 2a 20 74 68 61 74 20 77 65 20 68 61 76 65 20 74  * that we have t
2b40: 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20  aken it all out 
2b50: 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f  and gone back to
2b60: 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a   using simple.**
2b70: 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f   noop macros..*/
2b80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2b90: 44 45 50 52 45 43 41 54 45 44 0a 23 64 65 66 69  DEPRECATED.#defi
2ba0: 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49  ne SQLITE_EXPERI
2bb0: 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e  MENTAL../*.** En
2bc0: 73 75 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f  sure these symbo
2bd0: 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69  ls were not defi
2be0: 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76  ned by some prev
2bf0: 69 6f 75 73 20 68 65 61 64 65 72 20 66 69 6c 65  ious header file
2c00: 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49  ..*/.#ifdef SQLI
2c10: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64  TE_VERSION.# und
2c20: 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  ef SQLITE_VERSIO
2c30: 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20  N.#endif.#ifdef 
2c40: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
2c50: 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51  UMBER.# undef SQ
2c60: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
2c70: 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  BER.#endif../*.*
2c80: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
2c90: 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79  ile-Time Library
2ca0: 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73   Version Numbers
2cb0: 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51  .**.** ^(The [SQ
2cc0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20  LITE_VERSION] C 
2cd0: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
2ce0: 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ro in the sqlite
2cf0: 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 65 76  3.h header.** ev
2d00: 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73 74 72  aluates to a str
2d10: 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74  ing literal that
2d20: 20 69 73 20 74 68 65 20 53 51 4c 69 74 65 20 76   is the SQLite v
2d30: 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a  ersion in the.**
2d40: 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20   format "X.Y.Z" 
2d50: 77 68 65 72 65 20 58 20 69 73 20 74 68 65 20 6d  where X is the m
2d60: 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d  ajor version num
2d70: 62 65 72 20 28 61 6c 77 61 79 73 20 33 20 66 6f  ber (always 3 fo
2d80: 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 61 6e  r.** SQLite3) an
2d90: 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72  d Y is the minor
2da0: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20   version number 
2db0: 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72 65 6c  and Z is the rel
2dc0: 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a  ease number.)^.*
2dd0: 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f  * ^(The [SQLITE_
2de0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20  VERSION_NUMBER] 
2df0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
2e00: 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f  acro resolves to
2e10: 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77   an integer.** w
2e20: 69 74 68 20 74 68 65 20 76 61 6c 75 65 20 28 58  ith the value (X
2e30: 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30  *1000000 + Y*100
2e40: 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 20  0 + Z) where X, 
2e50: 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 68 65  Y, and Z are the
2e60: 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73   same.** numbers
2e70: 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 54 45   used in [SQLITE
2e80: 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20  _VERSION].)^.** 
2e90: 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49  The SQLITE_VERSI
2ea0: 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e  ON_NUMBER for an
2eb0: 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73 65 20  y given release 
2ec0: 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  of SQLite will a
2ed0: 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72  lso.** be larger
2ee0: 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65 61 73   than the releas
2ef0: 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69 74 20  e from which it 
2f00: 69 73 20 64 65 72 69 76 65 64 2e 20 20 45 69 74  is derived.  Eit
2f10: 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65  her Y will.** be
2f20: 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61   held constant a
2f30: 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63  nd Z will be inc
2f40: 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73 65  remented or else
2f50: 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65   Y will be incre
2f60: 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20  mented.** and Z 
2f70: 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20 74 6f  will be reset to
2f80: 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e   zero..**.** Sin
2f90: 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31  ce version 3.6.1
2fa0: 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65  8, SQLite source
2fb0: 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e 20 73   code has been s
2fc0: 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20  tored in the.** 
2fd0: 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f  <a href="http://
2fe0: 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f  www.fossil-scm.o
2ff0: 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f 6e 66  rg/">Fossil conf
3000: 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65  iguration manage
3010: 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f  ment.** system</
3020: 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45  a>.  ^The SQLITE
3030: 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63 72 6f  _SOURCE_ID macro
3040: 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a 2a 2a   evaluates to.**
3050: 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20   a string which 
3060: 69 64 65 6e 74 69 66 69 65 73 20 61 20 70 61 72  identifies a par
3070: 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d 69 6e  ticular check-in
3080: 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69   of SQLite.** wi
3090: 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69 67 75  thin its configu
30a0: 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e  ration managemen
30b0: 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68 65 20  t system.  ^The 
30c0: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
30d0: 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61  .** string conta
30e0: 69 6e 73 20 74 68 65 20 64 61 74 65 20 61 6e 64  ins the date and
30f0: 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63 68 65   time of the che
3100: 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e 64 20  ck-in (UTC) and 
3110: 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73 68 20  an SHA1.** hash 
3120: 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20 73 6f  of the entire so
3130: 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a 2a  urce tree..**.**
3140: 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
3150: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
3160: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c  ],.** [sqlite3_l
3170: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
3180: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6f  ()], [sqlite3_so
3190: 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b 73  urceid()],.** [s
31a0: 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d  qlite_version()]
31b0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75   and [sqlite_sou
31c0: 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23 64  rce_id()]..*/.#d
31d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52  efine SQLITE_VER
31e0: 53 49 4f 4e 20 20 20 20 20 20 20 20 22 33 2e 31  SION        "3.1
31f0: 32 2e 32 22 0a 23 64 65 66 69 6e 65 20 53 51 4c  2.2".#define SQL
3200: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
3210: 45 52 20 33 30 31 32 30 30 32 0a 23 64 65 66 69  ER 3012002.#defi
3220: 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45  ne SQLITE_SOURCE
3230: 5f 49 44 20 20 20 20 20 20 22 32 30 31 36 2d 30  _ID      "2016-0
3240: 34 2d 31 38 20 31 37 3a 33 30 3a 33 31 20 39 32  4-18 17:30:31 92
3250: 64 63 35 39 66 64 35 61 64 36 36 66 36 34 36 36  dc59fd5ad66f6466
3260: 36 36 30 34 32 65 62 30 34 31 39 35 65 33 61 36  66042eb04195e3a6
3270: 31 61 39 65 38 65 22 0a 0a 2f 2a 0a 2a 2a 20 43  1a9e8e"../*.** C
3280: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
3290: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
32a0: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
32b0: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
32c0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
32d0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
32e0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
32f0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
3300: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
3310: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
3320: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
3330: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
3340: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
3350: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
3360: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
3370: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
3380: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
3390: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
33a0: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
33b0: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
33c0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
33d0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
33e0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
33f0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
3400: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
3410: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
3420: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
3430: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
3440: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
3450: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
3460: 20 74 68 75 73 20 65 6e 73 75 72 65 20 74 68 61   thus ensure tha
3470: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
3480: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
3490: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
34a0: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
34b0: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
34c0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
34d0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
34e0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
34f0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
3500: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
3510: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
3520: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
3530: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
3540: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
3550: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
3560: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
3570: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
3580: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
3590: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
35a0: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
35b0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
35c0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
35d0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
35e0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
35f0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
3600: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
3610: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
3620: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
3630: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
3640: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
3650: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
3660: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
3670: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
3680: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
3690: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
36a0: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
36b0: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
36c0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
36d0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
36e0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
36f0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
3700: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
3710: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
3720: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
3730: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
3740: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
3750: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
3760: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
3770: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
3780: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
3790: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
37a0: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
37b0: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
37c0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
37d0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
37e0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
37f0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
3800: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
3810: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
3820: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
3830: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
3840: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
3850: 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69   const char sqli
3860: 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 3d 20  te3_version[] = 
3870: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 3b 0a  SQLITE_VERSION;.
3880: 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
3890: 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54   char *SQLITE_ST
38a0: 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6c 69  DCALL sqlite3_li
38b0: 62 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a  bversion(void);.
38c0: 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
38d0: 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54   char *SQLITE_ST
38e0: 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 6f  DCALL sqlite3_so
38f0: 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 53 51  urceid(void);.SQ
3900: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
3910: 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
3920: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
3930: 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a  umber(void);../*
3940: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
3950: 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 43  n-Time Library C
3960: 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69 6f  ompilation Optio
3970: 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 73 0a 2a  ns Diagnostics.*
3980: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
3990: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
39a0: 75 73 65 64 28 29 20 66 75 6e 63 74 69 6f 6e 20  used() function 
39b0: 72 65 74 75 72 6e 73 20 30 20 6f 72 20 31 20 0a  returns 0 or 1 .
39c0: 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 77 68  ** indicating wh
39d0: 65 74 68 65 72 20 74 68 65 20 73 70 65 63 69 66  ether the specif
39e0: 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 73 20 64  ied option was d
39f0: 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63 6f  efined at .** co
3a00: 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54 68  mpile time.  ^Th
3a10: 65 20 53 51 4c 49 54 45 5f 20 70 72 65 66 69 78  e SQLITE_ prefix
3a20: 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20   may be omitted 
3a30: 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70 74  from the .** opt
3a40: 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65 64 20  ion name passed 
3a50: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  to sqlite3_compi
3a60: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 2e  leoption_used().
3a70: 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71    .**.** ^The sq
3a80: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
3a90: 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63 74 69  ion_get() functi
3aa0: 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72 61 74  on allows iterat
3ab0: 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20  ing.** over the 
3ac0: 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73 20  list of options 
3ad0: 74 68 61 74 20 77 65 72 65 20 64 65 66 69 6e 65  that were define
3ae0: 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d  d at compile tim
3af0: 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69 6e  e by.** returnin
3b00: 67 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70 69  g the N-th compi
3b10: 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20 73  le time option s
3b20: 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69 73  tring.  ^If N is
3b30: 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a 2a   out of range,.*
3b40: 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  * sqlite3_compil
3b50: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 72 65  eoption_get() re
3b60: 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
3b70: 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 51 4c 49  nter.  ^The SQLI
3b80: 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20 69  TE_ .** prefix i
3b90: 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 61  s omitted from a
3ba0: 6e 79 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  ny strings retur
3bb0: 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74  ned by .** sqlit
3bc0: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
3bd0: 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53  _get()..**.** ^S
3be0: 75 70 70 6f 72 74 20 66 6f 72 20 74 68 65 20 64  upport for the d
3bf0: 69 61 67 6e 6f 73 74 69 63 20 66 75 6e 63 74 69  iagnostic functi
3c00: 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  ons sqlite3_comp
3c10: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
3c20: 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
3c30: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
3c40: 74 28 29 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  t() may be omitt
3c50: 65 64 20 62 79 20 73 70 65 63 69 66 79 69 6e 67  ed by specifying
3c60: 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
3c70: 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54  _OMIT_COMPILEOPT
3c80: 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69 6f  ION_DIAGS] optio
3c90: 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d  n at compile tim
3ca0: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
3cb0: 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  o: SQL functions
3cc0: 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65   [sqlite_compile
3cd0: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20 61  option_used()] a
3ce0: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63 6f  nd.** [sqlite_co
3cf0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
3d00: 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d 70  )] and the [comp
3d10: 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61 67  ile_options prag
3d20: 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20  ma]..*/.#ifndef 
3d30: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50  SQLITE_OMIT_COMP
3d40: 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 0a  ILEOPTION_DIAGS.
3d50: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
3d60: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
3d70: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
3d80: 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20 63  ion_used(const c
3d90: 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a  har *zOptName);.
3da0: 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
3db0: 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54   char *SQLITE_ST
3dc0: 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f  DCALL sqlite3_co
3dd0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
3de0: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
3df0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
3e00: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
3e10: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
3e20: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
3e30: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
3e40: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
3e50: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
3e60: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
3e70: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
3e80: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
3e90: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
3ea0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
3eb0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
3ec0: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
3ed0: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
3ee0: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
3ef0: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
3f00: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
3f10: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
3f20: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
3f30: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
3f40: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
3f50: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
3f60: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
3f70: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
3f80: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
3f90: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
3fa0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
3fb0: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
3fc0: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
3fd0: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
3fe0: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
3ff0: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
4000: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
4010: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
4020: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
4030: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
4040: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
4050: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
4060: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
4070: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
4080: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
4090: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
40a0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
40b0: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
40c0: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
40d0: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
40e0: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
40f0: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
4100: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
4110: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
4120: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
4130: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
4140: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
4150: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
4160: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
4170: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
4180: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
4190: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
41a0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
41b0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
41c0: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
41d0: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
41e0: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
41f0: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
4200: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
4210: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
4220: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
4230: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
4240: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
4250: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
4260: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
4270: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
4280: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
4290: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
42a0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
42b0: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
42c0: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
42d0: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
42e0: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
42f0: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
4300: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
4310: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
4320: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
4330: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
4340: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
4350: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
4360: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
4370: 4c 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72  LIZED].  ^(The r
4380: 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
4390: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68  he.** sqlite3_th
43a0: 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74  readsafe() funct
43b0: 69 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74  ion shows only t
43c0: 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  he compile-time 
43d0: 73 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68  setting of.** th
43e0: 72 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74  read safety, not
43f0: 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68   any run-time ch
4400: 61 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65  anges to that se
4410: 74 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a  tting made by.**
4420: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
4430: 29 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ). In other word
4440: 73 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  s, the return va
4450: 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
4460: 5f 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a  _threadsafe().**
4470: 20 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79   is unchanged by
4480: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
4490: 33 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a  3_config().)^.**
44a0: 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72  .** See the [thr
44b0: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63  eading mode] doc
44c0: 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61  umentation for a
44d0: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
44e0: 61 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ation..*/.SQLITE
44f0: 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
4500: 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
4510: 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 29  threadsafe(void)
4520: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
4530: 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
4540: 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a  ection Handle.**
4550: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 61   KEYWORDS: {data
4560: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d  base connection}
4570: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   {database conne
4580: 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61  ctions}.**.** Ea
4590: 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64  ch open SQLite d
45a0: 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65  atabase is repre
45b0: 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69 6e  sented by a poin
45c0: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
45d0: 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61  ce of.** the opa
45e0: 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e 61  que structure na
45f0: 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20 20  med "sqlite3".  
4600: 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f 20  It is useful to 
4610: 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69  think of an sqli
4620: 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61  te3.** pointer a
4630: 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68  s an object.  Th
4640: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  e [sqlite3_open(
4650: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
4660: 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  n16()], and.** [
4670: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
4680: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  )] interfaces ar
4690: 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f  e its constructo
46a0: 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  rs, and [sqlite3
46b0: 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 64  _close()].** and
46c0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f   [sqlite3_close_
46d0: 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64 65  v2()] are its de
46e0: 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65 72  structors.  Ther
46f0: 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72  e are many other
4700: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 28  .** interfaces (
4710: 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69  such as.** [sqli
4720: 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
4730: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ], [sqlite3_crea
4740: 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20  te_function()], 
4750: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
4760: 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20  busy_timeout()] 
4770: 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65  to name but thre
4780: 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74 68  e) that are meth
4790: 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c  ods on an.** sql
47a0: 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  ite3 object..*/.
47b0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
47c0: 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a  qlite3 sqlite3;.
47d0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
47e0: 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20   64-Bit Integer 
47f0: 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  Types.** KEYWORD
4800: 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  S: sqlite_int64 
4810: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a  sqlite_uint64.**
4820: 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 72  .** Because ther
4830: 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c  e is no cross-pl
4840: 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70  atform way to sp
4850: 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74  ecify 64-bit int
4860: 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51  eger types.** SQ
4870: 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79  Lite includes ty
4880: 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69  pedefs for 64-bi
4890: 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73  t signed and uns
48a0: 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a  igned integers..
48b0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
48c0: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
48d0: 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74  te3_uint64 are t
48e0: 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79 70  he preferred typ
48f0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a  e definitions..*
4900: 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74  * The sqlite_int
4910: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69  64 and sqlite_ui
4920: 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20 73  nt64 types are s
4930: 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63  upported for bac
4940: 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74  kwards.** compat
4950: 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a  ibility only..**
4960: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
4970: 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74  _int64 and sqlit
4980: 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63 61  e_int64 types ca
4990: 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20  n store integer 
49a0: 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65  values.** betwee
49b0: 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35 34  n -9223372036854
49c0: 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33  775808 and +9223
49d0: 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37 20  372036854775807 
49e0: 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65  inclusive.  ^The
49f0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  .** sqlite3_uint
4a00: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69  64 and sqlite_ui
4a10: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73  nt64 types can s
4a20: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c  tore integer val
4a30: 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20  ues .** between 
4a40: 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30  0 and +184467440
4a50: 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c  73709551615 incl
4a60: 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66  usive..*/.#ifdef
4a70: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
4a80: 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c  PE.  typedef SQL
4a90: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
4aa0: 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74  qlite_int64;.  t
4ab0: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
4ac0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
4ad0: 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b  E sqlite_uint64;
4ae0: 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f  .#elif defined(_
4af0: 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69  MSC_VER) || defi
4b00: 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f  ned(__BORLANDC__
4b10: 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e  ).  typedef __in
4b20: 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  t64 sqlite_int64
4b30: 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69  ;.  typedef unsi
4b40: 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c  gned __int64 sql
4b50: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73  ite_uint64;.#els
4b60: 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67  e.  typedef long
4b70: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
4b80: 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65  _int64;.  typede
4b90: 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20  f unsigned long 
4ba0: 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f  long int sqlite_
4bb0: 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74  uint64;.#endif.t
4bc0: 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e  ypedef sqlite_in
4bd0: 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  t64 sqlite3_int6
4be0: 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74  4;.typedef sqlit
4bf0: 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e_uint64 sqlite3
4c00: 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20  _uint64;../*.** 
4c10: 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72  If compiling for
4c20: 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61   a processor tha
4c30: 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67  t lacks floating
4c40: 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a   point support,.
4c50: 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69 6e  ** substitute in
4c60: 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69  teger for floati
4c70: 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66  ng-point..*/.#if
4c80: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
4c90: 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23  FLOATING_POINT.#
4ca0: 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73   define double s
4cb0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e  qlite3_int64.#en
4cc0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
4cd0: 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44  REF: Closing A D
4ce0: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
4cf0: 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f 52  on.** DESTRUCTOR
4d00: 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
4d10: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f  ^The sqlite3_clo
4d20: 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  se() and sqlite3
4d30: 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75 74  _close_v2() rout
4d40: 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75 63  ines are destruc
4d50: 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20  tors.** for the 
4d60: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
4d70: 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73  ..** ^Calls to s
4d80: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61  qlite3_close() a
4d90: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nd sqlite3_close
4da0: 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53 51  _v2() return [SQ
4db0: 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 74  LITE_OK] if.** t
4dc0: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
4dd0: 65 63 74 20 69 73 20 73 75 63 63 65 73 73 66 75  ect is successfu
4de0: 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61 6e  lly destroyed an
4df0: 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64  d all associated
4e00: 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61 72  .** resources ar
4e10: 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a  e deallocated..*
4e20: 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74  *.** ^If the dat
4e30: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
4e40: 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77   is associated w
4e50: 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20  ith unfinalized 
4e60: 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
4e70: 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e 69  ements or unfini
4e80: 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63  shed sqlite3_bac
4e90: 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65 6e  kup objects then
4ea0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
4eb0: 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20 74  .** will leave t
4ec0: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
4ed0: 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64 20  ection open and 
4ee0: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42  return [SQLITE_B
4ef0: 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  USY]..** ^If sql
4f00: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
4f10: 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 75  is called with u
4f20: 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 61  nfinalized prepa
4f30: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  red statements.*
4f40: 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69 73  * and/or unfinis
4f50: 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b  hed sqlite3_back
4f60: 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64 61  ups, then the da
4f70: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
4f80: 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20  n becomes.** an 
4f90: 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69 65  unusable "zombie
4fa0: 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75 74  " which will aut
4fb0: 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64 65  omatically be de
4fc0: 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20 74  allocated when t
4fd0: 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70 61  he.** last prepa
4fe0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73  red statement is
4ff0: 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74 68   finalized or th
5000: 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 62  e last sqlite3_b
5010: 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e 69  ackup is.** fini
5020: 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74  shed.  The sqlit
5030: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 6e  e3_close_v2() in
5040: 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65 6e  terface is inten
5050: 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74 68  ded for use with
5060: 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61 67  .** host languag
5070: 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72 62  es that are garb
5080: 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20 61  age collected, a
5090: 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72 64  nd where the ord
50a0: 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 64  er in which.** d
50b0: 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20 63  estructors are c
50c0: 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72 61  alled is arbitra
50d0: 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ry..**.** Applic
50e0: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73  ations should [s
50f0: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20  qlite3_finalize 
5100: 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20  | finalize] all 
5110: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
5120: 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  ents],.** [sqlit
5130: 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20  e3_blob_close | 
5140: 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42  close] all [BLOB
5150: 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20 0a   handles], and .
5160: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b  ** [sqlite3_back
5170: 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e 69  up_finish | fini
5180: 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33  sh] all [sqlite3
5190: 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73  _backup] objects
51a0: 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77   associated.** w
51b0: 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ith the [sqlite3
51c0: 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20 74  ] object prior t
51d0: 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20  o attempting to 
51e0: 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63 74  close the object
51f0: 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65  .  ^If.** sqlite
5200: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20  3_close_v2() is 
5210: 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61 74  called on a [dat
5220: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
5230: 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61 73  ] that still has
5240: 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67 20  .** outstanding 
5250: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
5260: 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e  ents], [BLOB han
5270: 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a  dles], and/or.**
5280: 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70   [sqlite3_backup
5290: 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 69  ] objects then i
52a0: 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  t returns [SQLIT
52b0: 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64 65  E_OK] and the de
52c0: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
52d0: 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64 65   resources is de
52e0: 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c  ferred until all
52f0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
5300: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
5310: 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b  ndles],.** and [
5320: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20  sqlite3_backup] 
5330: 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73 6f  objects are also
5340: 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a   destroyed..**.*
5350: 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74 65  * ^If an [sqlite
5360: 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65 73  3] object is des
5370: 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20 74  troyed while a t
5380: 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70  ransaction is op
5390: 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73  en,.** the trans
53a0: 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61  action is automa
53b0: 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
53c0: 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43  ack..**.** The C
53d0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
53e0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d  qlite3_close(C)]
53f0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c   and [sqlite3_cl
5400: 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75  ose_v2(C)].** mu
5410: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
5420: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
5430: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
5440: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
5450: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
5460: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
5470: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
5480: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
5490: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
54a0: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
54b0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
54c0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
54d0: 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74 65  lose() or sqlite
54e0: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69 74  3_close_v2() wit
54f0: 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
5500: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
5510: 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
5520: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
5530: 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
5540: 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  LL sqlite3_close
5550: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49  (sqlite3*);.SQLI
5560: 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
5570: 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
5580: 33 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74  3_close_v2(sqlit
5590: 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  e3*);../*.** The
55a0: 20 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c   type for a call
55b0: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  back function..*
55c0: 2a 20 54 68 69 73 20 69 73 20 6c 65 67 61 63 79  * This is legacy
55d0: 20 61 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e   and deprecated.
55e0: 20 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64    It is included
55f0: 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a   for historical.
5600: 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ** compatibility
5610: 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75   and is not docu
5620: 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64  mented..*/.typed
5630: 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33  ef int (*sqlite3
5640: 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a  _callback)(void*
5650: 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61  ,int,char**, cha
5660: 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  r**);../*.** CAP
5670: 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20  I3REF: One-Step 
5680: 51 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20  Query Execution 
5690: 49 6e 74 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54  Interface.** MET
56a0: 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
56b0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
56c0: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
56d0: 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65  is a convenience
56e0: 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a   wrapper around.
56f0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
5700: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
5710: 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64  te3_step()], and
5720: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
5730: 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61  ze()],.** that a
5740: 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61  llows an applica
5750: 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74  tion to run mult
5760: 69 70 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20  iple statements 
5770: 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75  of SQL.** withou
5780: 74 20 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20  t having to use 
5790: 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e  a lot of C code.
57a0: 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c   .**.** ^The sql
57b0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65  ite3_exec() inte
57c0: 72 66 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20  rface runs zero 
57d0: 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e  or more UTF-8 en
57e0: 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f  coded,.** semico
57f0: 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c  lon-separate SQL
5800: 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73   statements pass
5810: 65 64 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20  ed into its 2nd 
5820: 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20  argument,.** in 
5830: 74 68 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74  the context of t
5840: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
5850: 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20  nection] passed 
5860: 69 6e 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a  in as its 1st.**
5870: 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20   argument.  ^If 
5880: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  the callback fun
5890: 63 74 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64  ction of the 3rd
58a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
58b0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
58c0: 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
58d0: 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66   it is invoked f
58e0: 6f 72 20 65 61 63 68 20 72 65 73 75 6c 74 20 72  or each result r
58f0: 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74  ow.** coming out
5900: 20 6f 66 20 74 68 65 20 65 76 61 6c 75 61 74 65   of the evaluate
5910: 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  d SQL statements
5920: 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75  .  ^The 4th argu
5930: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  ment to.** sqlit
5940: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c  e3_exec() is rel
5950: 61 79 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20  ayed through to 
5960: 74 68 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74  the 1st argument
5970: 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c   of each.** call
5980: 62 61 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e  back invocation.
5990: 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61    ^If the callba
59a0: 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71  ck pointer to sq
59b0: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
59c0: 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f  is NULL, then no
59d0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65   callback is eve
59e0: 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65  r invoked and re
59f0: 73 75 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a  sult rows are.**
5a00: 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
5a10: 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  ^If an error occ
5a20: 75 72 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61  urs while evalua
5a30: 74 69 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61  ting the SQL sta
5a40: 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69  tements passed i
5a50: 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  nto.** sqlite3_e
5a60: 78 65 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63  xec(), then exec
5a70: 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72  ution of the cur
5a80: 72 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73  rent statement s
5a90: 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73  tops and.** subs
5aa0: 65 71 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74  equent statement
5ab0: 73 20 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20  s are skipped.  
5ac0: 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72 61  ^If the 5th para
5ad0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
5ae0: 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f  _exec().** is no
5af0: 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20  t NULL then any 
5b00: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73  error message is
5b10: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
5b20: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  mory obtained.**
5b30: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
5b40: 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73  alloc()] and pas
5b50: 73 65 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68  sed back through
5b60: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
5b70: 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20  er..** To avoid 
5b80: 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68  memory leaks, th
5b90: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
5ba0: 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  ould invoke [sql
5bb0: 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20  ite3_free()].** 
5bc0: 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  on error message
5bd0: 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
5be0: 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  d through the 5t
5bf0: 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a  h parameter of.*
5c00: 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  * sqlite3_exec()
5c10: 20 61 66 74 65 72 20 74 68 65 20 65 72 72 6f 72   after the error
5c20: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
5c30: 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65  is no longer nee
5c40: 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ded..** ^If the 
5c50: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
5c60: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
5c70: 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20  is not NULL and 
5c80: 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63  no errors.** occ
5c90: 75 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ur, then sqlite3
5ca0: 5f 65 78 65 63 28 29 20 73 65 74 73 20 74 68 65  _exec() sets the
5cb0: 20 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20   pointer in its 
5cc0: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
5cd0: 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20  .** NULL before 
5ce0: 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  returning..**.**
5cf0: 20 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f   ^If an sqlite3_
5d00: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
5d10: 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
5d20: 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78  , the sqlite3_ex
5d30: 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  ec().** routine 
5d40: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41  returns SQLITE_A
5d50: 42 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76  BORT without inv
5d60: 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61  oking the callba
5d70: 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20  ck again and.** 
5d80: 77 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20  without running 
5d90: 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 53  any subsequent S
5da0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
5db0: 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72  *.** ^The 2nd ar
5dc0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
5dd0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
5de0: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69  lback function i
5df0: 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
5e00: 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
5e10: 65 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20  e result.  ^The 
5e20: 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  3rd argument to 
5e30: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  the sqlite3_exec
5e40: 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69  ().** callback i
5e50: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
5e60: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
5e70: 73 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66  s obtained as if
5e80: 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65   from.** [sqlite
5e90: 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
5ea0: 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63  , one for each c
5eb0: 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65  olumn.  ^If an e
5ec0: 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72  lement of a.** r
5ed0: 65 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c  esult row is NUL
5ee0: 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65  L then the corre
5ef0: 73 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20  sponding string 
5f00: 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a  pointer for the.
5f10: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
5f20: 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  ) callback is a 
5f30: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e  NULL pointer.  ^
5f40: 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74  The 4th argument
5f50: 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74   to the.** sqlit
5f60: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
5f70: 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ck is an array o
5f80: 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  f pointers to st
5f90: 72 69 6e 67 73 20 77 68 65 72 65 20 65 61 63 68  rings where each
5fa0: 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73  .** entry repres
5fb0: 65 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  ents the name of
5fc0: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72   corresponding r
5fd0: 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20  esult column as 
5fe0: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
5ff0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
6000: 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _name()]..**.** 
6010: 5e 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61  ^If the 2nd para
6020: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
6030: 5f 65 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c  _exec() is a NUL
6040: 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69  L pointer, a poi
6050: 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d  nter.** to an em
6060: 70 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61  pty string, or a
6070: 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f   pointer that co
6080: 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74  ntains only whit
6090: 65 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a  espace and/or .*
60a0: 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20  * SQL comments, 
60b0: 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74  then no SQL stat
60c0: 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75  ements are evalu
60d0: 61 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 74  ated and the dat
60e0: 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20  abase.** is not 
60f0: 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52  changed..**.** R
6100: 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a  estrictions:.**.
6110: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
6120: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
6130: 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61 74  must ensure that
6140: 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74   the 1st paramet
6150: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
6160: 65 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20  ec().**      is 
6170: 61 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e  a valid and open
6180: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
6190: 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20  ction]..** <li> 
61a0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
61b0: 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74  must not close t
61c0: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
61d0: 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
61e0: 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68  ed by.**      th
61f0: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
6200: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
6210: 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f  ) while sqlite3_
6220: 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e  exec() is runnin
6230: 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  g..** <li> The a
6240: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
6250: 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53  not modify the S
6260: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
6270: 74 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a  t passed into.**
6280: 20 20 20 20 20 20 74 68 65 20 32 6e 64 20 70 61        the 2nd pa
6290: 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74  rameter of sqlit
62a0: 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20  e3_exec() while 
62b0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
62c0: 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f  s running..** </
62d0: 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ul>.*/.SQLITE_AP
62e0: 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
62f0: 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 78 65  CALL sqlite3_exe
6300: 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20  c(.  sqlite3*,  
6310: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6320: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6330: 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62  /* An open datab
6340: 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ase */.  const c
6350: 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20  har *sql,       
6360: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6370: 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65      /* SQL to be
6380: 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20   evaluated */.  
6390: 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28  int (*callback)(
63a0: 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a  void*,int,char**
63b0: 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61  ,char**),  /* Ca
63c0: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
63d0: 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20  */.  void *,    
63e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
63f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6400: 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20  /* 1st argument 
6410: 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20  to callback */. 
6420: 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20   char **errmsg  
6430: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6440: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45              /* E
6450: 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e  rror msg written
6460: 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a   here */.);../*.
6470: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
6480: 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59  ult Codes.** KEY
6490: 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63  WORDS: {result c
64a0: 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d  ode definitions}
64b0: 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69  .**.** Many SQLi
64c0: 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  te functions ret
64d0: 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72  urn an integer r
64e0: 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20  esult code from 
64f0: 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a  the set shown.**
6500: 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74   here in order t
6510: 6f 20 69 6e 64 69 63 61 74 65 20 73 75 63 63 65  o indicate succe
6520: 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a  ss or failure..*
6530: 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63  *.** New error c
6540: 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  odes may be adde
6550: 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  d in future vers
6560: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
6570: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
6580: 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
6590: 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e   code definition
65a0: 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s].*/.#define SQ
65b0: 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20  LITE_OK         
65c0: 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73    0   /* Success
65d0: 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a  ful result */./*
65e0: 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72   beginning-of-er
65f0: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65  ror-codes */.#de
6600: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f  fine SQLITE_ERRO
6610: 52 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20  R        1   /* 
6620: 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73  SQL error or mis
6630: 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f  sing database */
6640: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6650: 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20  INTERNAL     2  
6660: 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67   /* Internal log
6670: 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69  ic error in SQLi
6680: 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  te */.#define SQ
6690: 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20  LITE_PERM       
66a0: 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20    3   /* Access 
66b0: 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65  permission denie
66c0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
66d0: 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20  ITE_ABORT       
66e0: 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b   4   /* Callback
66f0: 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74   routine request
6700: 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23  ed an abort */.#
6710: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
6720: 53 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f  SY         5   /
6730: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66  * The database f
6740: 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f  ile is locked */
6750: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6760: 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20  LOCKED       6  
6770: 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74   /* A table in t
6780: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c  he database is l
6790: 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ocked */.#define
67a0: 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20   SQLITE_NOMEM   
67b0: 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61       7   /* A ma
67c0: 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f  lloc() failed */
67d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
67e0: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20  READONLY     8  
67f0: 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77   /* Attempt to w
6800: 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20  rite a readonly 
6810: 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66  database */.#def
6820: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  ine SQLITE_INTER
6830: 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f  RUPT    9   /* O
6840: 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61  peration termina
6850: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
6860: 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65  nterrupt()*/.#de
6870: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
6880: 52 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20  R       10   /* 
6890: 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73  Some kind of dis
68a0: 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75  k I/O error occu
68b0: 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rred */.#define 
68c0: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20  SQLITE_CORRUPT  
68d0: 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64     11   /* The d
68e0: 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61  atabase disk ima
68f0: 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20  ge is malformed 
6900: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6910: 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32  E_NOTFOUND    12
6920: 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70     /* Unknown op
6930: 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f  code in sqlite3_
6940: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a  file_control() *
6950: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6960: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20  _FULL        13 
6970: 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66    /* Insertion f
6980: 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61  ailed because da
6990: 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a  tabase is full *
69a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
69b0: 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20  _CANTOPEN    14 
69c0: 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f    /* Unable to o
69d0: 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
69e0: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
69f0: 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c   SQLITE_PROTOCOL
6a00: 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61      15   /* Data
6a10: 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63  base lock protoc
6a20: 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  ol error */.#def
6a30: 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59  ine SQLITE_EMPTY
6a40: 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44         16   /* D
6a50: 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79  atabase is empty
6a60: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6a70: 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31  TE_SCHEMA      1
6a80: 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  7   /* The datab
6a90: 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
6aa0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
6ab0: 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20  LITE_TOOBIG     
6ac0: 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20   18   /* String 
6ad0: 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20  or BLOB exceeds 
6ae0: 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64  size limit */.#d
6af0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
6b00: 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a  STRAINT  19   /*
6b10: 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f   Abort due to co
6b20: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
6b30: 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  on */.#define SQ
6b40: 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20  LITE_MISMATCH   
6b50: 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79   20   /* Data ty
6b60: 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23  pe mismatch */.#
6b70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49  define SQLITE_MI
6b80: 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f  SUSE      21   /
6b90: 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69  * Library used i
6ba0: 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64  ncorrectly */.#d
6bb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c  efine SQLITE_NOL
6bc0: 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a  FS       22   /*
6bd0: 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65   Uses OS feature
6be0: 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20  s not supported 
6bf0: 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69  on host */.#defi
6c00: 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20  ne SQLITE_AUTH  
6c10: 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75        23   /* Au
6c20: 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69  thorization deni
6c30: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
6c40: 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20  LITE_FORMAT     
6c50: 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61   24   /* Auxilia
6c60: 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d  ry database form
6c70: 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  at error */.#def
6c80: 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45  ine SQLITE_RANGE
6c90: 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32         25   /* 2
6ca0: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
6cb0: 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74  sqlite3_bind out
6cc0: 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65   of range */.#de
6cd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41  fine SQLITE_NOTA
6ce0: 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20  DB      26   /* 
6cf0: 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74  File opened that
6d00: 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61   is not a databa
6d10: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
6d20: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45  ne SQLITE_NOTICE
6d30: 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 4e 6f        27   /* No
6d40: 74 69 66 69 63 61 74 69 6f 6e 73 20 66 72 6f 6d  tifications from
6d50: 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a   sqlite3_log() *
6d60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6d70: 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 32 38 20  _WARNING     28 
6d80: 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20 66 72    /* Warnings fr
6d90: 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  om sqlite3_log()
6da0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6db0: 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31  TE_ROW         1
6dc0: 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73  00  /* sqlite3_s
6dd0: 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65  tep() has anothe
6de0: 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23  r row ready */.#
6df0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f  define SQLITE_DO
6e00: 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 20 2f  NE        101  /
6e10: 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
6e20: 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78   has finished ex
6e30: 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e  ecuting */./* en
6e40: 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73  d-of-error-codes
6e50: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
6e60: 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65  REF: Extended Re
6e70: 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45  sult Codes.** KE
6e80: 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65  YWORDS: {extende
6e90: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65  d result code de
6ea0: 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  finitions}.**.**
6eb0: 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20   In its default 
6ec0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53  configuration, S
6ed0: 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e  QLite API routin
6ee0: 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66  es return one of
6ef0: 20 33 30 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b   30 integer.** [
6f00: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20  result codes].  
6f10: 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65  However, experie
6f20: 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68  nce has shown th
6f30: 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68  at many of.** th
6f40: 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ese result codes
6f50: 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d   are too coarse-
6f60: 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64  grained.  They d
6f70: 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73  o not provide as
6f80: 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61  .** much informa
6f90: 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c  tion about probl
6fa0: 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65  ems as programme
6fb0: 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20  rs might like.  
6fc0: 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a  In an effort to.
6fd0: 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c  ** address this,
6fe0: 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20   newer versions 
6ff0: 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69  of SQLite (versi
7000: 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74  on 3.3.8 and lat
7010: 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73  er) include.** s
7020: 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74  upport for addit
7030: 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64  ional result cod
7040: 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20  es that provide 
7050: 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e  more detailed in
7060: 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f  formation.** abo
7070: 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65  ut errors. These
7080: 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
7090: 74 20 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61  t codes] are ena
70a0: 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
70b0: 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74  .** on a per dat
70c0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
70d0: 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65   basis using the
70e0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
70f0: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
7100: 65 73 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20  es()] API.  Or, 
7110: 74 68 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64  the extended cod
7120: 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73  e for.** the mos
7130: 74 20 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63  t recent error c
7140: 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75  an be obtained u
7150: 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
7160: 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
7170: 65 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  e()]..*/.#define
7180: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45   SQLITE_IOERR_RE
7190: 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AD              
71a0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
71b0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
71c0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f  SQLITE_IOERR_SHO
71d0: 52 54 5f 52 45 41 44 20 20 20 20 20 20 20 20 28  RT_READ        (
71e0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
71f0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
7200: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54  QLITE_IOERR_WRIT
7210: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  E             (S
7220: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33  QLITE_IOERR | (3
7230: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7240: 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43  LITE_IOERR_FSYNC
7250: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
7260: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c  LITE_IOERR | (4<
7270: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
7280: 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53  ITE_IOERR_DIR_FS
7290: 59 4e 43 20 20 20 20 20 20 20 20 20 28 53 51 4c  YNC         (SQL
72a0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c  ITE_IOERR | (5<<
72b0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
72c0: 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54  TE_IOERR_TRUNCAT
72d0: 45 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  E          (SQLI
72e0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38  TE_IOERR | (6<<8
72f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7300: 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20  E_IOERR_FSTAT   
7310: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
7320: 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29  E_IOERR | (7<<8)
7330: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
7340: 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20  _IOERR_UNLOCK   
7350: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
7360: 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29  _IOERR | (8<<8))
7370: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7380: 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20  IOERR_RDLOCK    
7390: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
73a0: 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a  IOERR | (9<<8)).
73b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
73c0: 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20  OERR_DELETE     
73d0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
73e0: 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a  OERR | (10<<8)).
73f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7400: 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20  OERR_BLOCKED    
7410: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
7420: 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a  OERR | (11<<8)).
7430: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7440: 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20  OERR_NOMEM      
7450: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
7460: 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a  OERR | (12<<8)).
7470: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7480: 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20 20 20  OERR_ACCESS     
7490: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
74a0: 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a  OERR | (13<<8)).
74b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
74c0: 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56  OERR_CHECKRESERV
74d0: 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49  EDLOCK (SQLITE_I
74e0: 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a  OERR | (14<<8)).
74f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7500: 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20  OERR_LOCK       
7510: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
7520: 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a  OERR | (15<<8)).
7530: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7540: 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  OERR_CLOSE      
7550: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
7560: 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a  OERR | (16<<8)).
7570: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7580: 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20  OERR_DIR_CLOSE  
7590: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
75a0: 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a  OERR | (17<<8)).
75b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
75c0: 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20  OERR_SHMOPEN    
75d0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
75e0: 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a  OERR | (18<<8)).
75f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7600: 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20 20 20 20  OERR_SHMSIZE    
7610: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
7620: 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a  OERR | (19<<8)).
7630: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7640: 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20  OERR_SHMLOCK    
7650: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
7660: 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a  OERR | (20<<8)).
7670: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7680: 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20 20 20 20  OERR_SHMMAP     
7690: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
76a0: 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a  OERR | (21<<8)).
76b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
76c0: 4f 45 52 52 5f 53 45 45 4b 20 20 20 20 20 20 20  OERR_SEEK       
76d0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
76e0: 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a  OERR | (22<<8)).
76f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7700: 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e  OERR_DELETE_NOEN
7710: 54 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49  T      (SQLITE_I
7720: 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38 29 29 0a  OERR | (23<<8)).
7730: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7740: 4f 45 52 52 5f 4d 4d 41 50 20 20 20 20 20 20 20  OERR_MMAP       
7750: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
7760: 4f 45 52 52 20 7c 20 28 32 34 3c 3c 38 29 29 0a  OERR | (24<<8)).
7770: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7780: 4f 45 52 52 5f 47 45 54 54 45 4d 50 50 41 54 48  OERR_GETTEMPPATH
7790: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
77a0: 4f 45 52 52 20 7c 20 28 32 35 3c 3c 38 29 29 0a  OERR | (25<<8)).
77b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
77c0: 4f 45 52 52 5f 43 4f 4e 56 50 41 54 48 20 20 20  OERR_CONVPATH   
77d0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
77e0: 4f 45 52 52 20 7c 20 28 32 36 3c 3c 38 29 29 0a  OERR | (26<<8)).
77f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7800: 4f 45 52 52 5f 56 4e 4f 44 45 20 20 20 20 20 20  OERR_VNODE      
7810: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
7820: 4f 45 52 52 20 7c 20 28 32 37 3c 3c 38 29 29 0a  OERR | (27<<8)).
7830: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7840: 4f 45 52 52 5f 41 55 54 48 20 20 20 20 20 20 20  OERR_AUTH       
7850: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
7860: 4f 45 52 52 20 7c 20 28 32 38 3c 3c 38 29 29 0a  OERR | (28<<8)).
7870: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
7880: 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48  OCKED_SHAREDCACH
7890: 45 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c  E      (SQLITE_L
78a0: 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29 29  OCKED |  (1<<8))
78b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
78c0: 42 55 53 59 5f 52 45 43 4f 56 45 52 59 20 20 20  BUSY_RECOVERY   
78d0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
78e0: 42 55 53 59 20 20 20 7c 20 20 28 31 3c 3c 38 29  BUSY   |  (1<<8)
78f0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
7900: 5f 42 55 53 59 5f 53 4e 41 50 53 48 4f 54 20 20  _BUSY_SNAPSHOT  
7910: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
7920: 5f 42 55 53 59 20 20 20 7c 20 20 28 32 3c 3c 38  _BUSY   |  (2<<8
7930: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7940: 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d  E_CANTOPEN_NOTEM
7950: 50 44 49 52 20 20 20 20 20 20 28 53 51 4c 49 54  PDIR      (SQLIT
7960: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c  E_CANTOPEN | (1<
7970: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
7980: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44  ITE_CANTOPEN_ISD
7990: 49 52 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  IR          (SQL
79a0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
79b0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
79c0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46  QLITE_CANTOPEN_F
79d0: 55 4c 4c 50 41 54 48 20 20 20 20 20 20 20 28 53  ULLPATH       (S
79e0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
79f0: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (3<<8)).#define
7a00: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
7a10: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20  _CONVPATH       
7a20: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  (SQLITE_CANTOPEN
7a30: 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69   | (4<<8)).#defi
7a40: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
7a50: 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 20  T_VTAB          
7a60: 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50    (SQLITE_CORRUP
7a70: 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  T | (1<<8)).#def
7a80: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
7a90: 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20  NLY_RECOVERY    
7aa0: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
7ab0: 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  NLY | (1<<8)).#d
7ac0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
7ad0: 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20  DONLY_CANTLOCK  
7ae0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
7af0: 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a  DONLY | (2<<8)).
7b00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
7b10: 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b  EADONLY_ROLLBACK
7b20: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
7b30: 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29  EADONLY | (3<<8)
7b40: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
7b50: 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45  _READONLY_DBMOVE
7b60: 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  D        (SQLITE
7b70: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c  _READONLY | (4<<
7b80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
7b90: 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 43  TE_ABORT_ROLLBAC
7ba0: 4b 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  K          (SQLI
7bb0: 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c 38  TE_ABORT | (2<<8
7bc0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7bd0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48 45  E_CONSTRAINT_CHE
7be0: 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  CK        (SQLIT
7bf0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
7c00: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
7c10: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
7c20: 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 28 53  _COMMITHOOK   (S
7c30: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
7c40: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
7c50: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
7c60: 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 59 20  AINT_FOREIGNKEY 
7c70: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
7c80: 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29 0a 23  AINT | (3<<8)).#
7c90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
7ca0: 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54 49 4f  NSTRAINT_FUNCTIO
7cb0: 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f  N     (SQLITE_CO
7cc0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c 3c 38  NSTRAINT | (4<<8
7cd0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7ce0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f 54  E_CONSTRAINT_NOT
7cf0: 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c 49 54  NULL      (SQLIT
7d00: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
7d10: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  5<<8)).#define S
7d20: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
7d30: 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20 28 53  _PRIMARYKEY   (S
7d40: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
7d50: 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69   | (6<<8)).#defi
7d60: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
7d70: 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20 20 20  AINT_TRIGGER    
7d80: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
7d90: 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29 0a 23  AINT | (7<<8)).#
7da0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
7db0: 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55 45 20  NSTRAINT_UNIQUE 
7dc0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
7dd0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c 3c 38  NSTRAINT | (8<<8
7de0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7df0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54 41  E_CONSTRAINT_VTA
7e00: 42 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  B         (SQLIT
7e10: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
7e20: 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  9<<8)).#define S
7e30: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
7e40: 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20 28 53  _ROWID        (S
7e50: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
7e60: 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69   |(10<<8)).#defi
7e70: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45  ne SQLITE_NOTICE
7e80: 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 20 20  _RECOVER_WAL    
7e90: 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45    (SQLITE_NOTICE
7ea0: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
7eb0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45  ne SQLITE_NOTICE
7ec0: 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43  _RECOVER_ROLLBAC
7ed0: 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45  K (SQLITE_NOTICE
7ee0: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
7ef0: 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e  ne SQLITE_WARNIN
7f00: 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20 20 20  G_AUTOINDEX     
7f10: 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e    (SQLITE_WARNIN
7f20: 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  G | (1<<8)).#def
7f30: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 5f  ine SQLITE_AUTH_
7f40: 55 53 45 52 20 20 20 20 20 20 20 20 20 20 20 20  USER            
7f50: 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54 48 20     (SQLITE_AUTH 
7f60: 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a  | (1<<8))../*.**
7f70: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
7f80: 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f   For File Open O
7f90: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  perations.**.** 
7fa0: 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73  These bit values
7fb0: 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
7fc0: 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20  r use in the.** 
7fd0: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
7fe0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   the [sqlite3_op
7ff0: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
8000: 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65  ce and.** in the
8010: 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
8020: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  o the [sqlite3_v
8030: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64  fs.xOpen] method
8040: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
8050: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
8060: 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30  Y         0x0000
8070: 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0001  /* Ok for 
8080: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
8090: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
80a0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
80b0: 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  TE        0x0000
80c0: 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0002  /* Ok for 
80d0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
80e0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
80f0: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20  ITE_OPEN_CREATE 
8100: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
8110: 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0004  /* Ok for 
8120: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
8130: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
8140: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
8150: 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30  NCLOSE    0x0000
8160: 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0008  /* VFS onl
8170: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
8180: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
8190: 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  VE        0x0000
81a0: 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0010  /* VFS onl
81b0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
81c0: 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f  ITE_OPEN_AUTOPRO
81d0: 58 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30  XY        0x0000
81e0: 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0020  /* VFS onl
81f0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
8200: 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20  ITE_OPEN_URI    
8210: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
8220: 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0040  /* Ok for 
8230: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
8240: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
8250: 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20  ITE_OPEN_MEMORY 
8260: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
8270: 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0080  /* Ok for 
8280: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
8290: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
82a0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
82b0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
82c0: 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0100  /* VFS onl
82d0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
82e0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
82f0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
8300: 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0200  /* VFS onl
8310: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
8320: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
8330: 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30  NT_DB     0x0000
8340: 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0400  /* VFS onl
8350: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
8360: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
8370: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
8380: 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0800  /* VFS onl
8390: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
83a0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
83b0: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
83c0: 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  1000  /* VFS onl
83d0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
83e0: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
83f0: 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30  NAL       0x0000
8400: 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  2000  /* VFS onl
8410: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
8420: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
8430: 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30  JOURNAL   0x0000
8440: 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  4000  /* VFS onl
8450: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
8460: 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
8470: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
8480: 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  8000  /* Ok for 
8490: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
84a0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
84b0: 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
84c0: 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31  EX        0x0001
84d0: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0000  /* Ok for 
84e0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
84f0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
8500: 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
8510: 41 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32  ACHE      0x0002
8520: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0000  /* Ok for 
8530: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
8540: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
8550: 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
8560: 43 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34  CACHE     0x0004
8570: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0000  /* Ok for 
8580: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
8590: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
85a0: 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20  ITE_OPEN_WAL    
85b0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38            0x0008
85c0: 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0000  /* VFS onl
85d0: 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65  y */../* Reserve
85e0: 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  d:              
85f0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 46             0x00F
8600: 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  00000 */../*.** 
8610: 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65  CAPI3REF: Device
8620: 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73   Characteristics
8630: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69  .**.** The xDevi
8640: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
8650: 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
8660: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
8670: 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72  ods].** object r
8680: 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65  eturns an intege
8690: 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63  r which is a vec
86a0: 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  tor of these.** 
86b0: 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65  bit values expre
86c0: 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63  ssing I/O charac
86d0: 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65  teristics of the
86e0: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a   mass storage.**
86f0: 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c   device that hol
8700: 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74  ds the file that
8710: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
8720: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66  _methods].** ref
8730: 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68  ers to..**.** Th
8740: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
8750: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
8760: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
8770: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
8780: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
8790: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
87a0: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
87b0: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
87c0: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
87d0: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
87e0: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
87f0: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
8800: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
8810: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
8820: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
8830: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
8840: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
8850: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
8860: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
8870: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
8880: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
8890: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
88a0: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
88b0: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
88c0: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
88d0: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
88e0: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
88f0: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
8900: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
8910: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
8920: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
8930: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
8940: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
8950: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
8960: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
8970: 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45  e().  The SQLITE
8980: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
8990: 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65  _OVERWRITE prope
89a0: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
89b0: 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66  * after reboot f
89c0: 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68  ollowing a crash
89d0: 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20   or power loss, 
89e0: 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69  the only bytes i
89f0: 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74  n a.** file that
8a00: 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74   were written at
8a10: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
8a20: 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76   level might hav
8a30: 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64  e changed.** and
8a40: 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62   that adjacent b
8a50: 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73  ytes, even bytes
8a60: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
8a70: 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67   sector are.** g
8a80: 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20  uaranteed to be 
8a90: 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20  unchanged.  The 
8aa0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44  SQLITE_IOCAP_UND
8ab0: 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50  ELETABLE_WHEN_OP
8ac0: 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63  EN.** flag indic
8ad0: 61 74 65 20 74 68 61 74 20 61 20 66 69 6c 65 20  ate that a file 
8ae0: 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65  cannot be delete
8af0: 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68  d when open.  Th
8b00: 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41  e.** SQLITE_IOCA
8b10: 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67  P_IMMUTABLE flag
8b20: 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20   indicates that 
8b30: 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a  the file is on.*
8b40: 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69  * read-only medi
8b50: 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20  a and cannot be 
8b60: 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20  changed even by 
8b70: 70 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a  processes with.*
8b80: 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69 76 69  * elevated privi
8b90: 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e  leges..*/.#defin
8ba0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
8bb0: 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 20  TOMIC           
8bc0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
8bd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8be0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20  IOCAP_ATOMIC512 
8bf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
8c00: 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20  0000002.#define 
8c10: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8c20: 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20 20 20  MIC1K           
8c30: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23      0x00000004.#
8c40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
8c50: 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20  CAP_ATOMIC2K    
8c60: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
8c70: 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51  00008.#define SQ
8c80: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8c90: 43 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C4K             
8ca0: 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65    0x00000010.#de
8cb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
8cc0: 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20  P_ATOMIC8K      
8cd0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
8ce0: 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  020.#define SQLI
8cf0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
8d00: 36 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  6K              
8d10: 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69  0x00000040.#defi
8d20: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
8d30: 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20  ATOMIC32K       
8d40: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38         0x0000008
8d50: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
8d60: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b  _IOCAP_ATOMIC64K
8d70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
8d80: 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65  00000100.#define
8d90: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
8da0: 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20  FE_APPEND       
8db0: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a       0x00000200.
8dc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
8dd0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
8de0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
8df0: 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53  000400.#define S
8e00: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45  QLITE_IOCAP_UNDE
8e10: 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45  LETABLE_WHEN_OPE
8e20: 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a 23 64  N  0x00000800.#d
8e30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
8e40: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
8e50: 52 57 52 49 54 45 20 20 20 20 30 78 30 30 30 30  RWRITE    0x0000
8e60: 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  1000.#define SQL
8e70: 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41  ITE_IOCAP_IMMUTA
8e80: 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20  BLE             
8e90: 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f 2a 0a   0x00002000../*.
8ea0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c  ** CAPI3REF: Fil
8eb0: 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73  e Locking Levels
8ec0: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
8ed0: 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  es one of these 
8ee0: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61  integer values a
8ef0: 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
8f00: 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c  argument to call
8f10: 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68  s it makes to th
8f20: 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  e xLock() and xU
8f30: 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a  nlock() methods.
8f40: 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  ** of an [sqlite
8f50: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
8f60: 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ject..*/.#define
8f70: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e   SQLITE_LOCK_NON
8f80: 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65  E          0.#de
8f90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
8fa0: 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31  _SHARED        1
8fb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8fc0: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20  LOCK_RESERVED   
8fd0: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
8fe0: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
8ff0: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
9000: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43   SQLITE_LOCK_EXC
9010: 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a  LUSIVE     4../*
9020: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79  .** CAPI3REF: Sy
9030: 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79  nchronization Ty
9040: 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57  pe Flags.**.** W
9050: 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b  hen SQLite invok
9060: 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d  es the xSync() m
9070: 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b  ethod of an.** [
9080: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
9090: 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73  ds] object it us
90a0: 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  es a combination
90b0: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74   of.** these int
90c0: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
90d0: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
90e0: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  nt..**.** When t
90f0: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  he SQLITE_SYNC_D
9100: 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20  ATAONLY flag is 
9110: 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74  used, it means t
9120: 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20  hat the.** sync 
9130: 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e  operation only n
9140: 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61  eeds to flush da
9150: 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61  ta to mass stora
9160: 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e  ge.  Inode.** in
9170: 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e  formation need n
9180: 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49  ot be flushed. I
9190: 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72  f the lower four
91a0: 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61   bits of the fla
91b0: 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54  g.** equal SQLIT
91c0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74  E_SYNC_NORMAL, t
91d0: 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65  hat means to use
91e0: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20   normal fsync() 
91f0: 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66  semantics..** If
9200: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
9210: 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54  bits equal SQLIT
9220: 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61  E_SYNC_FULL, tha
9230: 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73  t means.** to us
9240: 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65  e Mac OS X style
9250: 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61   fullsync instea
9260: 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  d of fsync()..**
9270: 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75  .** Do not confu
9280: 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59  se the SQLITE_SY
9290: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
92a0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
92b0: 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65  lags.** with the
92c0: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
92d0: 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64  nous]=NORMAL and
92e0: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
92f0: 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65  nous]=FULL.** se
9300: 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79  ttings.  The [sy
9310: 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61  nchronous pragma
9320: 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65  ] determines whe
9330: 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a  n calls to the.*
9340: 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68  * xSync VFS meth
9350: 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70  od occur and app
9360: 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61  lies uniformly a
9370: 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f  cross all platfo
9380: 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49  rms..** The SQLI
9390: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
93a0: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
93b0: 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d  ULL flags determ
93c0: 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67  ine how.** energ
93d0: 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73  etic or rigorous
93e0: 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65   or forceful the
93f0: 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73   sync operations
9400: 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79   are and.** only
9410: 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e   make a differen
9420: 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f  ce on Mac OSX fo
9430: 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 53 51  r the default SQ
9440: 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54  Lite code..** (T
9450: 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 20 69  hird-party VFS i
9460: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
9470: 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74  ight also make t
9480: 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a  he distinction.*
9490: 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45  * between SQLITE
94a0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
94b0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
94c0: 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65  L, but among the
94d0: 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79  .** operating sy
94e0: 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73  stems natively s
94f0: 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
9500: 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58  te, only Mac OSX
9510: 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20  .** cares about 
9520: 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29  the difference.)
9530: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
9540: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20  TE_SYNC_NORMAL  
9550: 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64        0x00002.#d
9560: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
9570: 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20  C_FULL          
9580: 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20  0x00003.#define 
9590: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
95a0: 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31  ONLY      0x0001
95b0: 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
95c0: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
95d0: 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65  Open File Handle
95e0: 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74  .**.** An [sqlit
95f0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
9600: 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70  represents an op
9610: 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a  en file in the .
9620: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20  ** [sqlite3_vfs 
9630: 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  | OS interface l
9640: 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75  ayer].  Individu
9650: 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a  al OS interface.
9660: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
9670: 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20  ns will.** want 
9680: 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73  to subclass this
9690: 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e   object by appen
96a0: 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20  ding additional 
96b0: 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68  fields.** for th
96c0: 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68  eir own use.  Th
96d0: 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79  e pMethods entry
96e0: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
96f0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
9700: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
9710: 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
9720: 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66  methods for perf
9730: 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70  orming.** I/O op
9740: 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20  erations on the 
9750: 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79  open file..*/.ty
9760: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
9770: 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65  ite3_file sqlite
9780: 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73  3_file;.struct s
9790: 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20  qlite3_file {.  
97a0: 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c  const struct sql
97b0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
97c0: 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d  *pMethods;  /* M
97d0: 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70  ethods for an op
97e0: 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f  en file */.};../
97f0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
9800: 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65  S Interface File
9810: 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73   Virtual Methods
9820: 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76   Object.**.** Ev
9830: 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20  ery file opened 
9840: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
9850: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
9860: 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a  d populates an.*
9870: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  * [sqlite3_file]
9880: 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72   object (or, mor
9890: 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75  e commonly, a su
98a0: 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a  bclass of the.**
98b0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
98c0: 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70  object) with a p
98d0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
98e0: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
98f0: 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62  ject..** This ob
9900: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
9910: 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f   methods used to
9920: 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
9930: 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61   operations.** a
9940: 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20  gainst the open 
9950: 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64  file represented
9960: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
9970: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a  _file] object..*
9980: 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c  *.** If the [sql
9990: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
99a0: 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65 20  method sets the 
99b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
99c0: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a  thods element .*
99d0: 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  * to a non-NULL 
99e0: 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68  pointer, then th
99f0: 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  e sqlite3_io_met
9a00: 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68  hods.xClose meth
9a10: 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76  od.** may be inv
9a20: 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68 65  oked even if the
9a30: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
9a40: 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68  pen] reported th
9a50: 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54  at it failed.  T
9a60: 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74  he.** only way t
9a70: 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c  o prevent a call
9a80: 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f   to xClose follo
9a90: 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73  wing a failed [s
9aa0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
9ab0: 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20  ].** is for the 
9ac0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
9ad0: 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73  en] to set the s
9ae0: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
9af0: 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20  hods element.** 
9b00: 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54  to NULL..**.** T
9b10: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
9b20: 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62  t to xSync may b
9b30: 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  e one of [SQLITE
9b40: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72  _SYNC_NORMAL] or
9b50: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  .** [SQLITE_SYNC
9b60: 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72  _FULL].  The fir
9b70: 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 65  st choice is the
9b80: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e   normal fsync().
9b90: 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63  .** The second c
9ba0: 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f  hoice is a Mac O
9bb0: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79  S X style fullsy
9bc0: 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  nc.  The [SQLITE
9bd0: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a  _SYNC_DATAONLY].
9be0: 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f  ** flag may be O
9bf0: 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61  Red in to indica
9c00: 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65  te that only the
9c10: 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c   data of the fil
9c20: 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73  e.** and not its
9c30: 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20   inode needs to 
9c40: 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a  be synced..**.**
9c50: 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c   The integer val
9c60: 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61  ues to xLock() a
9c70: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65  nd xUnlock() are
9c80: 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a   one of.** <ul>.
9c90: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
9ca0: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c  LOCK_NONE],.** <
9cb0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
9cc0: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  _SHARED],.** <li
9cd0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  > [SQLITE_LOCK_R
9ce0: 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  ESERVED],.** <li
9cf0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  > [SQLITE_LOCK_P
9d00: 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c  ENDING], or.** <
9d10: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
9d20: 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20  _EXCLUSIVE]..** 
9d30: 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29  </ul>.** xLock()
9d40: 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c   increases the l
9d50: 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64  ock. xUnlock() d
9d60: 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ecreases the loc
9d70: 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b  k..** The xCheck
9d80: 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d  ReservedLock() m
9d90: 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65  ethod checks whe
9da0: 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61 73  ther any databas
9db0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a  e connection,.**
9dc0: 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 20   either in this 
9dd0: 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f  process or in so
9de0: 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  me other process
9df0: 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52  , is holding a R
9e00: 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44  ESERVED,.** PEND
9e10: 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56  ING, or EXCLUSIV
9e20: 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69  E lock on the fi
9e30: 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20  le.  It returns 
9e40: 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20  true.** if such 
9e50: 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e  a lock exists an
9e60: 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73  d false otherwis
9e70: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69  e..**.** The xFi
9e80: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68  leControl() meth
9e90: 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 20  od is a generic 
9ea0: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
9eb0: 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20  llows custom.** 
9ec0: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
9ed0: 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20  ons to directly 
9ee0: 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20  control an open 
9ef0: 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a  file using the.*
9f00: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
9f10: 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72  control()] inter
9f20: 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e  face.  The secon
9f30: 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20  d "op" argument 
9f40: 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72  is an.** integer
9f50: 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68   opcode.  The th
9f60: 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
9f70: 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65  a generic pointe
9f80: 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a  r intended to.**
9f90: 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75   point to a stru
9fa0: 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 63  cture that may c
9fb0: 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73  ontain arguments
9fc0: 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 69   or space in whi
9fd0: 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72  ch to.** write r
9fe0: 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50  eturn values.  P
9ff0: 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f  otential uses fo
a000: 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29  r xFileControl()
a010: 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e   might be.** fun
a020: 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65  ctions to enable
a030: 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20   blocking locks 
a040: 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74  with timeouts, t
a050: 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20  o change the.** 
a060: 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79  locking strategy
a070: 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f   (for example to
a080: 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f   use dot-file lo
a090: 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65  cks), to inquire
a0a0: 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74  .** about the st
a0b0: 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20  atus of a lock, 
a0c0: 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c  or to break stal
a0d0: 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51  e locks.  The SQ
a0e0: 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73  Lite.** core res
a0f0: 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65  erves all opcode
a100: 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  s less than 100 
a110: 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e  for its own use.
a120: 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74  .** A [file cont
a130: 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69  rol opcodes | li
a140: 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c  st of opcodes] l
a150: 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20  ess than 100 is 
a160: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70  available..** Ap
a170: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
a180: 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20  define a custom 
a190: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
a1a0: 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f  hod should use o
a1b0: 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65  pcodes.** greate
a1c0: 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76  r than 100 to av
a1d0: 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20  oid conflicts.  
a1e0: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
a1f0: 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ons should.** re
a200: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54  turn [SQLITE_NOT
a210: 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20  FOUND] for file 
a220: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20  control opcodes 
a230: 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74  that they do not
a240: 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a  .** recognize..*
a250: 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72  *.** The xSector
a260: 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65  Size() method re
a270: 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72  turns the sector
a280: 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20   size of the.** 
a290: 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65  device that unde
a2a0: 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20  rlies the file. 
a2b0: 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   The sector size
a2c0: 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d   is the.** minim
a2d0: 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61  um write that ca
a2e0: 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77  n be performed w
a2f0: 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e  ithout disturbin
a300: 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73  g.** other bytes
a310: 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54   in the file.  T
a320: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
a330: 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d  teristics().** m
a340: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
a350: 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72  bit vector descr
a360: 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20  ibing behaviors 
a370: 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c  of the.** underl
a380: 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a  ying device:.**.
a390: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
a3a0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
a3b0: 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  OMIC].** <li> [S
a3c0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
a3d0: 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC512].** <li> [
a3e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
a3f0: 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC1K].** <li> [
a400: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
a410: 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC2K].** <li> [
a420: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
a430: 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC4K].** <li> [
a440: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
a450: 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC8K].** <li> [
a460: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
a470: 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC16K].** <li> 
a480: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
a490: 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC32K].** <li>
a4a0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
a4b0: 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC64K].** <li
a4c0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
a4d0: 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20  SAFE_APPEND].** 
a4e0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
a4f0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a  AP_SEQUENTIAL].*
a500: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
a510: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
a520: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
a530: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
a540: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
a550: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
a560: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
a570: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
a580: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
a590: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
a5a0: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
a5b0: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
a5c0: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
a5d0: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
a5e0: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
a5f0: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
a600: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
a610: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
a620: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
a630: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
a640: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
a650: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
a660: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
a670: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
a680: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
a690: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
a6a0: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
a6b0: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
a6c0: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
a6d0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
a6e0: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
a6f0: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
a700: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
a710: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
a720: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
a730: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
a740: 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52  e()..**.** If xR
a750: 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51  ead() returns SQ
a760: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
a770: 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c  _READ it must al
a780: 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68  so fill.** in th
a790: 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e  e unread portion
a7a0: 73 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20  s of the buffer 
a7b0: 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56  with zeros.  A V
a7c0: 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73  FS that.** fails
a7d0: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68   to zero-fill sh
a7e0: 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20  ort reads might 
a7f0: 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48  seem to work.  H
a800: 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75  owever,.** failu
a810: 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  re to zero-fill 
a820: 73 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c  short reads will
a830: 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64   eventually lead
a840: 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20   to.** database 
a850: 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74  corruption..*/.t
a860: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
a870: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
a880: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
a890: 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
a8a0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b  te3_io_methods {
a8b0: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
a8c0: 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29  .  int (*xClose)
a8d0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
a8e0: 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28  .  int (*xRead)(
a8f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76  sqlite3_file*, v
a900: 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20  oid*, int iAmt, 
a910: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
a920: 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57  fst);.  int (*xW
a930: 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69  rite)(sqlite3_fi
a940: 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  le*, const void*
a950: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69  , int iAmt, sqli
a960: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29  te3_int64 iOfst)
a970: 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63  ;.  int (*xTrunc
a980: 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ate)(sqlite3_fil
a990: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
a9a0: 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  4 size);.  int (
a9b0: 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xSync)(sqlite3_
a9c0: 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73  file*, int flags
a9d0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
a9e0: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69  Size)(sqlite3_fi
a9f0: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
aa00: 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e  64 *pSize);.  in
aa10: 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74  t (*xLock)(sqlit
aa20: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
aa30: 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29    int (*xUnlock)
aa40: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
aa50: 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  int);.  int (*xC
aa60: 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b  heckReservedLock
aa70: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
aa80: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a   int *pResOut);.
aa90: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e    int (*xFileCon
aaa0: 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69  trol)(sqlite3_fi
aab0: 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69  le*, int op, voi
aac0: 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20  d *pArg);.  int 
aad0: 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73  (*xSectorSize)(s
aae0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
aaf0: 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68   int (*xDeviceCh
ab00: 61 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73  aracteristics)(s
ab10: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
ab20: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
ab30: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
ab40: 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69  version 1 */.  i
ab50: 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71  nt (*xShmMap)(sq
ab60: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
ab70: 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20   iPg, int pgsz, 
ab80: 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69  int, void volati
ab90: 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  le**);.  int (*x
aba0: 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  ShmLock)(sqlite3
abb0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73  _file*, int offs
abc0: 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66  et, int n, int f
abd0: 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a  lags);.  void (*
abe0: 78 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c  xShmBarrier)(sql
abf0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
ac00: 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28  nt (*xShmUnmap)(
ac10: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
ac20: 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a  nt deleteFlag);.
ac30: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f    /* Methods abo
ac40: 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72  ve are valid for
ac50: 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20   version 2 */.  
ac60: 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28 73 71  int (*xFetch)(sq
ac70: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
ac80: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
ac90: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64  , int iAmt, void
aca0: 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28 2a   **pp);.  int (*
acb0: 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69 74 65  xUnfetch)(sqlite
acc0: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
acd0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 76 6f  _int64 iOfst, vo
ace0: 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74  id *p);.  /* Met
acf0: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76  hods above are v
ad00: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e  alid for version
ad10: 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74   3 */.  /* Addit
ad20: 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61  ional methods ma
ad30: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
ad40: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f  ture releases */
ad50: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
ad60: 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69  REF: Standard Fi
ad70: 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64  le Control Opcod
ad80: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
ad90: 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70  {file control op
ada0: 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63 6f 6e  codes} {file con
adb0: 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a 2a 0a  trol opcode}.**.
adc0: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
add0: 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f   constants are o
ade0: 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78  pcodes for the x
adf0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
ae00: 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  od.** of the [sq
ae10: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
ae20: 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72  ] object and for
ae30: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
ae40: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a  le_control()].**
ae50: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
ae60: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b  * <ul>.** <li>[[
ae70: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
ae80: 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68 65 20  KSTATE]].** The 
ae90: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f  [SQLITE_FCNTL_LO
aea0: 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20  CKSTATE] opcode 
aeb0: 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75  is used for debu
aec0: 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20  gging.  This.** 
aed0: 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68  opcode causes th
aee0: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
aef0: 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74  ethod to write t
af00: 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65  he current state
af10: 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20   of.** the lock 
af20: 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f  (one of [SQLITE_
af30: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c  LOCK_NONE], [SQL
af40: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d  ITE_LOCK_SHARED]
af50: 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  ,.** [SQLITE_LOC
af60: 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51  K_RESERVED], [SQ
af70: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
af80: 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c  G], or [SQLITE_L
af90: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a  OCK_EXCLUSIVE]).
afa0: 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67  ** into an integ
afb0: 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72 67  er that the pArg
afc0: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73   argument points
afd0: 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69   to. This capabi
afe0: 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20  lity.** is used 
aff0: 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61  during testing a
b000: 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  nd is only avail
b010: 61 62 6c 65 20 77 68 65 6e 20 74 68 65 20 53 51  able when the SQ
b020: 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63 6f 6d  LITE_TEST.** com
b030: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
b040: 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
b050: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
b060: 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a  TL_SIZE_HINT]].*
b070: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
b080: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f  NTL_SIZE_HINT] o
b090: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 62 79  pcode is used by
b0a0: 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76 65 20   SQLite to give 
b0b0: 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72  the VFS.** layer
b0c0: 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c   a hint of how l
b0d0: 61 72 67 65 20 74 68 65 20 64 61 74 61 62 61 73  arge the databas
b0e0: 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77  e file will grow
b0f0: 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20 74 68   to be during th
b100: 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 72 61  e.** current tra
b110: 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 73 20  nsaction.  This 
b120: 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 61 72  hint is not guar
b130: 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61 63 63  anteed to be acc
b140: 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a 2a 20  urate but it.** 
b150: 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20  is often close. 
b160: 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   The underlying 
b170: 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f 73 65  VFS might choose
b180: 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65 20   to preallocate 
b190: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
b1a0: 20 73 70 61 63 65 20 62 61 73 65 64 20 6f 6e 20   space based on 
b1b0: 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f 72 64  this hint in ord
b1c0: 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69 74 65  er to help write
b1d0: 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  s to the databas
b1e0: 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66 61  e.** file run fa
b1f0: 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ster..**.** <li>
b200: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  [[SQLITE_FCNTL_C
b210: 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54  HUNK_SIZE]].** T
b220: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b230: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63  _CHUNK_SIZE] opc
b240: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 72  ode is used to r
b250: 65 71 75 65 73 74 20 74 68 61 74 20 74 68 65 20  equest that the 
b260: 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61  VFS.** extends a
b270: 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74 68 65  nd truncates the
b280: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
b290: 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69  n chunks of a si
b2a0: 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ze specified.** 
b2b0: 62 79 20 74 68 65 20 75 73 65 72 2e 20 54 68 65  by the user. The
b2c0: 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
b2d0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c   to [sqlite3_fil
b2e0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f  e_control()] sho
b2f0: 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f  uld .** point to
b300: 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70   an integer (typ
b310: 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e  e int) containin
b320: 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d  g the new chunk-
b330: 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66  size to use.** f
b340: 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64  or the nominated
b350: 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63   database. Alloc
b360: 61 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 66  ating database f
b370: 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72  ile space in lar
b380: 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61  ge.** chunks (sa
b390: 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29  y 1MB at a time)
b3a0: 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c  , may reduce fil
b3b0: 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e  e-system fragmen
b3c0: 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d  tation and.** im
b3d0: 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63  prove performanc
b3e0: 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d  e on some system
b3f0: 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  s..**.** <li>[[S
b400: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
b410: 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68  _POINTER]].** Th
b420: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b430: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70  FILE_POINTER] op
b440: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
b450: 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72  obtain a pointer
b460: 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
b470: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
b480: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
b490: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61   a particular da
b4a0: 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
b4b0: 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20  tion.  See also 
b4c0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f  [SQLITE_FCNTL_JO
b4d0: 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 2e 0a  URNAL_POINTER]..
b4e0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b4f0: 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c  TE_FCNTL_JOURNAL
b500: 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68  _POINTER]].** Th
b510: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b520: 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d  JOURNAL_POINTER]
b530: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
b540: 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e  to obtain a poin
b550: 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  ter.** to the [s
b560: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
b570: 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77  ect associated w
b580: 69 74 68 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20  ith the journal 
b590: 66 69 6c 65 20 28 65 69 74 68 65 72 0a 2a 2a 20  file (either.** 
b5a0: 74 68 65 20 5b 72 6f 6c 6c 62 61 63 6b 20 6a 6f  the [rollback jo
b5b0: 75 72 6e 61 6c 5d 20 6f 72 20 74 68 65 20 5b 77  urnal] or the [w
b5c0: 72 69 74 65 2d 61 68 65 61 64 20 6c 6f 67 5d 29  rite-ahead log])
b5d0: 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
b5e0: 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  r database.** co
b5f0: 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 61  nnection.  See a
b600: 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  lso [SQLITE_FCNT
b610: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 2e  L_FILE_POINTER].
b620: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b630: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f  ITE_FCNTL_SYNC_O
b640: 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c  MITTED]].** No l
b650: 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a  onger in use..**
b660: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
b670: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a  _FCNTL_SYNC]].**
b680: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
b690: 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20  TL_SYNC] opcode 
b6a0: 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74  is generated int
b6b0: 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74  ernally by SQLit
b6c0: 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f  e and.** sent to
b6d0: 20 74 68 65 20 56 46 53 20 69 6d 6d 65 64 69 61   the VFS immedia
b6e0: 74 65 6c 79 20 62 65 66 6f 72 65 20 74 68 65 20  tely before the 
b6f0: 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20  xSync method is 
b700: 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20  invoked on a.** 
b710: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 64 65  database file de
b720: 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66  scriptor. Or, if
b730: 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f   the xSync metho
b740: 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64  d is not invoked
b750: 20 0a 2a 2a 20 62 65 63 61 75 73 65 20 74 68 65   .** because the
b760: 20 75 73 65 72 20 68 61 73 20 63 6f 6e 66 69 67   user has config
b770: 75 72 65 64 20 53 51 4c 69 74 65 20 77 69 74 68  ured SQLite with
b780: 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e   .** [PRAGMA syn
b790: 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d  chronous | PRAGM
b7a0: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46  A synchronous=OF
b7b0: 46 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64  F] it is invoked
b7c0: 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66   in place .** of
b7d0: 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f   the xSync metho
b7e0: 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73 65 73  d. In most cases
b7f0: 2c 20 74 68 65 20 70 6f 69 6e 74 65 72 20 61 72  , the pointer ar
b800: 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 77 69  gument passed wi
b810: 74 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d  th.** this file-
b820: 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e  control is NULL.
b830: 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68 65   However, if the
b840: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
b850: 73 20 62 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a  s being synced.*
b860: 2a 20 61 73 20 70 61 72 74 20 6f 66 20 61 20 6d  * as part of a m
b870: 75 6c 74 69 2d 64 61 74 61 62 61 73 65 20 63 6f  ulti-database co
b880: 6d 6d 69 74 2c 20 74 68 65 20 61 72 67 75 6d 65  mmit, the argume
b890: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e  nt points to a n
b8a0: 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ul-terminated.**
b8b0: 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69   string containi
b8c0: 6e 67 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ng the transacti
b8d0: 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e  ons master-journ
b8e0: 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46  al file name. VF
b8f0: 53 65 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20  Ses that .** do 
b900: 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69  not need this si
b910: 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65  gnal should sile
b920: 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73  ntly ignore this
b930: 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61   opcode. Applica
b940: 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64  tions .** should
b950: 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74   not call [sqlit
b960: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
b970: 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63  )] with this opc
b980: 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20  ode as doing so 
b990: 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75 70 74 20  may .** disrupt 
b9a0: 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66  the operation of
b9b0: 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64   the specialized
b9c0: 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72   VFSes that do r
b9d0: 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a  equire it.  .**.
b9e0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
b9f0: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41  FCNTL_COMMIT_PHA
ba00: 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b  SETWO]].** The [
ba10: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
ba20: 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70  MIT_PHASETWO] op
ba30: 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65  code is generate
ba40: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20  d internally by 
ba50: 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65  SQLite.** and se
ba60: 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 61 66  nt to the VFS af
ba70: 74 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ter a transactio
ba80: 6e 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69  n has been commi
ba90: 74 74 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  tted immediately
baa0: 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72 65 20 74  .** but before t
bab0: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 75  he database is u
bac0: 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73 20 74  nlocked. VFSes t
bad0: 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  hat do not need 
bae0: 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73  this signal.** s
baf0: 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69  hould silently i
bb00: 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64  gnore this opcod
bb10: 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  e. Applications 
bb20: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a  should not call.
bb30: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
bb40: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68  _control()] with
bb50: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20   this opcode as 
bb60: 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73  doing so may dis
bb70: 72 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65  rupt the .** ope
bb80: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70  ration of the sp
bb90: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20  ecialized VFSes 
bba0: 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20  that do require 
bbb0: 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  it.  .**.** <li>
bbc0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  [[SQLITE_FCNTL_W
bbd0: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a  IN32_AV_RETRY]].
bbe0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
bbf0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
bc00: 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20  ETRY] opcode is 
bc10: 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72  used to configur
bc20: 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72  e automatic.** r
bc30: 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20  etry counts and 
bc40: 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65  intervals for ce
bc50: 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f  rtain disk I/O o
bc60: 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68  perations for th
bc70: 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46  e.** windows [VF
bc80: 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70  S] in order to p
bc90: 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73  rovide robustnes
bca0: 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63  s in the presenc
bcb0: 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72  e of.** anti-vir
bcc0: 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79  us programs.  By
bcd0: 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69   default, the wi
bce0: 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72  ndows VFS will r
bcf0: 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a  etry file read,.
bd00: 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61  ** file write, a
bd10: 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f  nd file delete o
bd20: 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20  perations up to 
bd30: 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61  10 times, with a
bd40: 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20   delay.** of 25 
bd50: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66  milliseconds bef
bd60: 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 72 65  ore the first re
bd70: 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 68 65  try and with the
bd80: 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e   delay increasin
bd90: 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74  g.** by an addit
bda0: 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65  ional 25 millise
bdb0: 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68 20  conds with each 
bdc0: 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 72 79  subsequent retry
bdd0: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
bde0: 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74  e allows these t
bdf0: 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72 65  wo values (10 re
be00: 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c  tries and 25 mil
be10: 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c  liseconds of del
be20: 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a  ay).** to be adj
be30: 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75  usted.  The valu
be40: 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 20 66  es are changed f
be50: 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20  or all database 
be60: 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77  connections.** w
be70: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70  ithin the same p
be80: 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72 67  rocess.  The arg
be90: 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
bea0: 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f  er to an array o
beb0: 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72  f two.** integer
bec0: 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73  s where the firs
bed0: 74 20 69 6e 74 65 67 65 72 20 69 20 74 68 65 20  t integer i the 
bee0: 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20  new retry count 
bef0: 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a  and the second.*
bf00: 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65  * integer is the
bf10: 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68   delay.  If eith
bf20: 65 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65  er integer is ne
bf30: 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  gative, then the
bf40: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e   setting.** is n
bf50: 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 69  ot changed but i
bf60: 6e 73 74 65 61 64 20 74 68 65 20 70 72 69 6f 72  nstead the prior
bf70: 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73   value of that s
bf80: 65 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 65  etting is writte
bf90: 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72  n.** into the ar
bfa0: 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77  ray entry, allow
bfb0: 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 20  ing the current 
bfc0: 72 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 74  retry settings t
bfd0: 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67  o be.** interrog
bfe0: 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61  ated.  The zDbNa
bff0: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  me parameter is 
c000: 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  ignored..**.** <
c010: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
c020: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a  L_PERSIST_WAL]].
c030: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
c040: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41  FCNTL_PERSIST_WA
c050: 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  L] opcode is use
c060: 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72  d to set or quer
c070: 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74  y the.** persist
c080: 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65  ent [WAL | Write
c090: 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74   Ahead Log] sett
c0a0: 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74  ing.  By default
c0b0: 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a  , the auxiliary.
c0c0: 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 6c  ** write ahead l
c0d0: 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65  og and shared me
c0e0: 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64 20  mory files used 
c0f0: 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  for transaction 
c100: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61  control.** are a
c110: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c  utomatically del
c120: 65 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61  eted when the la
c130: 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  test connection 
c140: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  to the database.
c150: 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74  ** closes.  Sett
c160: 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 57  ing persistent W
c170: 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74  AL mode causes t
c180: 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65  hose files to pe
c190: 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63  rsist after.** c
c1a0: 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e  lose.  Persistin
c1b0: 67 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 75  g the files is u
c1c0: 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72  seful when other
c1d0: 20 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 20   processes that 
c1e0: 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77  do not.** have w
c1f0: 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20  rite permission 
c200: 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 79  on the directory
c210: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
c220: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61  database file wa
c230: 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68  nt.** to read th
c240: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c  e database file,
c250: 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20   as the WAL and 
c260: 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69  shared memory fi
c270: 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a  les must exist.*
c280: 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74  * in order for t
c290: 68 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 62  he database to b
c2a0: 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65  e readable.  The
c2b0: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
c2c0: 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
c2d0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
c2e0: 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65   for this opcode
c2f0: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69   should be a poi
c300: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
c310: 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65  er..** That inte
c320: 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61  ger is 0 to disa
c330: 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 57  ble persistent W
c340: 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20  AL mode or 1 to 
c350: 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e  enable persisten
c360: 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20  t.** WAL mode.  
c370: 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69  If the integer i
c380: 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73  s -1, then it is
c390: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74   overwritten wit
c3a0: 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  h the current.**
c3b0: 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65   WAL persistence
c3c0: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   setting..**.** 
c3d0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
c3e0: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  TL_POWERSAFE_OVE
c3f0: 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65  RWRITE]].** ^The
c400: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
c410: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
c420: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  TE] opcode is us
c430: 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65  ed to set or que
c440: 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73  ry the.** persis
c450: 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d  tent "powersafe-
c460: 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 50  overwrite" or "P
c470: 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54  SOW" setting.  T
c480: 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a  he PSOW setting.
c490: 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  ** determines th
c4a0: 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  e [SQLITE_IOCAP_
c4b0: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
c4c0: 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a  ITE] bit of the.
c4d0: 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 63  ** xDeviceCharac
c4e0: 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64  teristics method
c4f0: 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  s. The fourth pa
c500: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
c510: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
c520: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
c530: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
c540: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
c550: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
c560: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
c570: 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64  o disable zero-d
c580: 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20  amage mode or 1 
c590: 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64  to enable zero-d
c5a0: 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20  amage.** mode.  
c5b0: 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69  If the integer i
c5c0: 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73  s -1, then it is
c5d0: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74   overwritten wit
c5e0: 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  h the current.**
c5f0: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64   zero-damage mod
c600: 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a  e setting..**.**
c610: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
c620: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a  NTL_OVERWRITE]].
c630: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
c640: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d  FCNTL_OVERWRITE]
c650: 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b   opcode is invok
c660: 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74  ed by SQLite aft
c670: 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20  er opening.** a 
c680: 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f  write transactio
c690: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
c6a0: 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73  at, unless it is
c6b0: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72   rolled back for
c6c0: 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c   some.** reason,
c6d0: 20 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61   the entire data
c6e0: 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62  base file will b
c6f0: 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79  e overwritten by
c700: 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a   the current .**
c710: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68   transaction. Th
c720: 69 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41  is is used by VA
c730: 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e  CUUM operations.
c740: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
c750: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
c760: 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  E]].** ^The [SQL
c770: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
c780: 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65  E] opcode can be
c790: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
c7a0: 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20  the names of.** 
c7b0: 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74  all [VFSes] in t
c7c0: 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54  he VFS stack.  T
c7d0: 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20  he names are of 
c7e0: 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e  all VFS shims an
c7f0: 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62  d the.** final b
c800: 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20  ottom-level VFS 
c810: 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  are written into
c820: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
c830: 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74   from .** [sqlit
c840: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64  e3_malloc()] and
c850: 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73   the result is s
c860: 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61  tored in the cha
c870: 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74  r* variable.** t
c880: 68 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70  hat the fourth p
c890: 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c  arameter of [sql
c8a0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
c8b0: 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a  l()] points to..
c8c0: 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73  ** The caller is
c8d0: 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
c8e0: 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d   freeing the mem
c8f0: 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20  ory when done.  
c900: 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66  As with.** all f
c910: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69  ile-control acti
c920: 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f  ons, there is no
c930: 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20   guarantee that 
c940: 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c  this will actual
c950: 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e  ly.** do anythin
c960: 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75  g.  Callers shou
c970: 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68  ld initialize th
c980: 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65  e char* variable
c990: 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f   to a NULL.** po
c9a0: 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68  inter in case th
c9b0: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  is file-control 
c9c0: 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74  is not implement
c9d0: 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63  ed.  This file-c
c9e0: 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74  ontrol.** is int
c9f0: 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f  ended for diagno
ca00: 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a  stic use only..*
ca10: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
ca20: 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e  E_FCNTL_VFS_POIN
ca30: 54 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  TER]].** ^The [S
ca40: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f  QLITE_FCNTL_VFS_
ca50: 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20  POINTER] opcode 
ca60: 66 69 6e 64 73 20 61 20 70 6f 69 6e 74 65 72 20  finds a pointer 
ca70: 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c  to the top-level
ca80: 0a 2a 2a 20 5b 56 46 53 65 73 5d 20 63 75 72 72  .** [VFSes] curr
ca90: 65 6e 74 6c 79 20 69 6e 20 75 73 65 2e 20 20 5e  ently in use.  ^
caa0: 28 54 68 65 20 61 72 67 75 6d 65 6e 74 20 58 20  (The argument X 
cab0: 69 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69  in.** sqlite3_fi
cac0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 64 62 2c 53 51  le_control(db,SQ
cad0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50  LITE_FCNTL_VFS_P
cae0: 4f 49 4e 54 45 52 2c 58 29 20 6d 75 73 74 20 62  OINTER,X) must b
caf0: 65 0a 2a 2a 20 6f 66 20 74 79 70 65 20 22 5b 73  e.** of type "[s
cb00: 71 6c 69 74 65 33 5f 76 66 73 5d 20 2a 2a 22 2e  qlite3_vfs] **".
cb10: 20 20 54 68 69 73 20 6f 70 63 6f 64 65 73 20 77    This opcodes w
cb20: 69 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a 20 74 6f  ill set *X.** to
cb30: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
cb40: 65 20 74 6f 70 2d 6c 65 76 65 6c 20 56 46 53 2e  e top-level VFS.
cb50: 29 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 72  )^.** ^When ther
cb60: 65 20 61 72 65 20 6d 75 6c 74 69 70 6c 65 20 56  e are multiple V
cb70: 46 53 20 73 68 69 6d 73 20 69 6e 20 74 68 65 20  FS shims in the 
cb80: 73 74 61 63 6b 2c 20 74 68 69 73 20 6f 70 63 6f  stack, this opco
cb90: 64 65 20 66 69 6e 64 73 20 74 68 65 0a 2a 2a 20  de finds the.** 
cba0: 75 70 70 65 72 2d 6d 6f 73 74 20 73 68 69 6d 20  upper-most shim 
cbb0: 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  only..**.** <li>
cbc0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  [[SQLITE_FCNTL_P
cbd0: 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e  RAGMA]].** ^When
cbe0: 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20  ever a [PRAGMA] 
cbf0: 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72  statement is par
cc00: 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f  sed, an [SQLITE_
cc10: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a  FCNTL_PRAGMA] .*
cc20: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  * file control i
cc30: 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70  s sent to the op
cc40: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  en [sqlite3_file
cc50: 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70  ] object corresp
cc60: 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65  onding.** to the
cc70: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74   database file t
cc80: 6f 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67  o which the prag
cc90: 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66  ma statement ref
cca0: 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65  ers. ^The argume
ccb0: 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51  nt.** to the [SQ
ccc0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
ccd0: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
cce0: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a  is an array of.*
ccf0: 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  * pointers to st
cd00: 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69  rings (char**) i
cd10: 6e 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f  n which the seco
cd20: 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68  nd element of th
cd30: 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68  e array.** is th
cd40: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72  e name of the pr
cd50: 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69  agma and the thi
cd60: 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68  rd element is th
cd70: 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  e argument to th
cd80: 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e  e.** pragma or N
cd90: 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d  ULL if the pragm
cda0: 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e  a has no argumen
cdb0: 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72  t.  ^The handler
cdc0: 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49   for an.** [SQLI
cdd0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
cde0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61   file control ca
cdf0: 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b  n optionally mak
ce00: 65 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d  e the first elem
ce10: 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68  ent.** of the ch
ce20: 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f  ar** argument po
ce30: 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20  int to a string 
ce40: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
ce50: 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
ce60: 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69  ].** or the equi
ce70: 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20  valent and that 
ce80: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f  string will beco
ce90: 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  me the result of
cea0: 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a   the pragma or.*
ceb0: 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  * the error mess
cec0: 61 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d  age if the pragm
ced0: 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65  a fails. ^If the
cee0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
cef0: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
cf00: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b  ontrol returns [
cf10: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
cf20: 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a  , then normal .*
cf30: 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65  * [PRAGMA] proce
cf40: 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e  ssing continues.
cf50: 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54    ^If the [SQLIT
cf60: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a  E_FCNTL_PRAGMA].
cf70: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
cf80: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
cf90: 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61  OK], then the pa
cfa0: 72 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61  rser assumes tha
cfb0: 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73  t the.** VFS has
cfc0: 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41   handled the PRA
cfd0: 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74  GMA itself and t
cfe0: 68 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61  he parser genera
cff0: 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70  tes a no-op.** p
d000: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
d010: 74 20 69 66 20 72 65 73 75 6c 74 20 73 74 72 69  t if result stri
d020: 6e 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72 20 74  ng is NULL, or t
d030: 68 61 74 20 72 65 74 75 72 6e 73 20 61 20 63 6f  hat returns a co
d040: 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73  py.** of the res
d050: 75 6c 74 20 73 74 72 69 6e 67 20 69 66 20 74 68  ult string if th
d060: 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 6e 2d  e string is non-
d070: 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  NULL..** ^If the
d080: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
d090: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
d0a0: 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  rol returns.** a
d0b0: 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f  ny result code o
d0c0: 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
d0d0: 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45  E_OK] or [SQLITE
d0e0: 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74  _NOTFOUND], that
d0f0: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74   means.** that t
d100: 68 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72  he VFS encounter
d110: 65 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c  ed an error whil
d120: 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b  e handling the [
d130: 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a  PRAGMA] and the.
d140: 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f  ** compilation o
d150: 66 20 74 68 65 20 50 52 41 47 4d 41 20 66 61 69  f the PRAGMA fai
d160: 6c 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  ls with an error
d170: 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  .  ^The [SQLITE_
d180: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a  FCNTL_PRAGMA].**
d190: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63   file control oc
d1a0: 63 75 72 73 20 61 74 20 74 68 65 20 62 65 67 69  curs at the begi
d1b0: 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20  nning of pragma 
d1c0: 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73  statement analys
d1d0: 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20  is and so.** it 
d1e0: 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72  is able to overr
d1f0: 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52  ide built-in [PR
d200: 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73  AGMA] statements
d210: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
d220: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48  LITE_FCNTL_BUSYH
d230: 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65  ANDLER]].** ^The
d240: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42   [SQLITE_FCNTL_B
d250: 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66  USYHANDLER].** f
d260: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20  ile-control may 
d270: 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51  be invoked by SQ
d280: 4c 69 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61  Lite on the data
d290: 62 61 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65  base file handle
d2a0: 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65  .** shortly afte
d2b0: 72 20 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69  r it is opened i
d2c0: 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69  n order to provi
d2d0: 64 65 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20  de a custom VFS 
d2e0: 77 69 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74  with access.** t
d2f0: 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  o the connection
d300: 73 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63  s busy-handler c
d310: 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67  allback. The arg
d320: 75 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65  ument is of type
d330: 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20   (void **).** - 
d340: 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20  an array of two 
d350: 28 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e  (void *) values.
d360: 20 54 68 65 20 66 69 72 73 74 20 28 76 6f 69 64   The first (void
d370: 20 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69   *) actually poi
d380: 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63  nts.** to a func
d390: 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e  tion of type (in
d3a0: 74 20 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20  t (*)(void *)). 
d3b0: 49 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f  In order to invo
d3c0: 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  ke the connectio
d3d0: 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c  ns.** busy-handl
d3e0: 65 72 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  er, this functio
d3f0: 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f  n should be invo
d400: 6b 65 64 20 77 69 74 68 20 74 68 65 20 73 65 63  ked with the sec
d410: 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a  ond (void *) in.
d420: 2a 2a 20 74 68 65 20 61 72 72 61 79 20 61 73 20  ** the array as 
d430: 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e  the only argumen
d440: 74 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73  t. If it returns
d450: 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
d460: 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  the operation.**
d470: 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69   should be retri
d480: 65 64 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e  ed. If it return
d490: 73 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74  s zero, the cust
d4a0: 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62  om VFS should ab
d4b0: 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72  andon the.** cur
d4c0: 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a  rent operation..
d4d0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
d4e0: 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c  TE_FCNTL_TEMPFIL
d4f0: 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c  ENAME]].** ^Appl
d500: 69 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f  ication can invo
d510: 6b 65 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  ke the [SQLITE_F
d520: 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d  CNTL_TEMPFILENAM
d530: 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a  E] file-control.
d540: 2a 2a 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74  ** to have SQLit
d550: 65 20 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20  e generate a.** 
d560: 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61  temporary filena
d570: 6d 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d  me using the sam
d580: 65 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74  e algorithm that
d590: 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20   is followed to 
d5a0: 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70  generate.** temp
d5b0: 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20  orary filenames 
d5c0: 66 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20  for TEMP tables 
d5d0: 61 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e  and other intern
d5e0: 61 6c 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a  al uses.  The.**
d5f0: 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
d600: 20 62 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69   be a char** whi
d610: 63 68 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65  ch will be fille
d620: 64 20 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e  d with the filen
d630: 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69  ame.** written i
d640: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
d650: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
d660: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68  3_malloc()].  Th
d670: 65 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a  e caller should.
d680: 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  ** invoke [sqlit
d690: 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68  e3_free()] on th
d6a0: 65 20 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69  e result to avoi
d6b0: 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e  d a memory leak.
d6c0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
d6d0: 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53  ITE_FCNTL_MMAP_S
d6e0: 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  IZE]].** The [SQ
d6f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f  LITE_FCNTL_MMAP_
d700: 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72  SIZE] file contr
d710: 6f 6c 20 69 73 20 75 73 65 64 20 74 6f 20 71 75  ol is used to qu
d720: 65 72 79 20 6f 72 20 73 65 74 20 74 68 65 0a 2a  ery or set the.*
d730: 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  * maximum number
d740: 20 6f 66 20 62 79 74 65 73 20 74 68 61 74 20 77   of bytes that w
d750: 69 6c 6c 20 62 65 20 75 73 65 64 20 66 6f 72 20  ill be used for 
d760: 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f  memory-mapped I/
d770: 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  O..** The argume
d780: 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
d790: 74 6f 20 61 20 76 61 6c 75 65 20 6f 66 20 74 79  to a value of ty
d7a0: 70 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  pe sqlite3_int64
d7b0: 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61   that.** is an a
d7c0: 64 76 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20  dvisory maximum 
d7d0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
d7e0: 69 6e 20 74 68 65 20 66 69 6c 65 20 74 6f 20 6d  in the file to m
d7f0: 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68 65 0a  emory map.  The.
d800: 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 6f 76  ** pointer is ov
d810: 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74  erwritten with t
d820: 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54  he old value.  T
d830: 68 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20  he limit is not 
d840: 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68  changed if.** th
d850: 65 20 76 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c  e value original
d860: 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73  ly pointed to is
d870: 20 6e 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73   negative, and s
d880: 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69  o the current li
d890: 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71  mit .** can be q
d8a0: 75 65 72 69 65 64 20 62 79 20 70 61 73 73 69 6e  ueried by passin
d8b0: 67 20 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74  g in a pointer t
d8c0: 6f 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d  o a negative num
d8d0: 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69  ber.  This.** fi
d8e0: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73  le-control is us
d8f0: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f  ed internally to
d900: 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47   implement [PRAG
d910: 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a  MA mmap_size]..*
d920: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
d930: 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a  E_FCNTL_TRACE]].
d940: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
d950: 43 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65  CNTL_TRACE] file
d960: 20 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65   control provide
d970: 73 20 61 64 76 69 73 6f 72 79 20 69 6e 66 6f 72  s advisory infor
d980: 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65  mation.** to the
d990: 20 56 46 53 20 61 62 6f 75 74 20 77 68 61 74 20   VFS about what 
d9a0: 74 68 65 20 68 69 67 68 65 72 20 6c 61 79 65 72  the higher layer
d9b0: 73 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20  s of the SQLite 
d9c0: 73 74 61 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e  stack are doing.
d9d0: 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f  .** This file co
d9e0: 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 62 79  ntrol is used by
d9f0: 20 73 6f 6d 65 20 56 46 53 20 61 63 74 69 76 69   some VFS activi
da00: 74 79 20 74 72 61 63 69 6e 67 20 5b 73 68 69 6d  ty tracing [shim
da10: 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d  s]..** The argum
da20: 65 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d 74 65  ent is a zero-te
da30: 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 2e  rminated string.
da40: 20 20 48 69 67 68 65 72 20 6c 61 79 65 72 73 20    Higher layers 
da50: 69 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65  in the.** SQLite
da60: 20 73 74 61 63 6b 20 6d 61 79 20 67 65 6e 65 72   stack may gener
da70: 61 74 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66  ate instances of
da80: 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72   this file contr
da90: 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51  ol if.** the [SQ
daa0: 4c 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54  LITE_USE_FCNTL_T
dab0: 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  RACE] compile-ti
dac0: 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61  me option is ena
dad0: 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  bled..**.** <li>
dae0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48  [[SQLITE_FCNTL_H
daf0: 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68  AS_MOVED]].** Th
db00: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
db10: 48 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20  HAS_MOVED] file 
db20: 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65  control interpre
db30: 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20  ts its argument 
db40: 61 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  as a.** pointer 
db50: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e  to an integer an
db60: 64 20 69 74 20 77 72 69 74 65 73 20 61 20 62 6f  d it writes a bo
db70: 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61 74 20  olean into that 
db80: 69 6e 74 65 67 65 72 20 64 65 70 65 6e 64 69 6e  integer dependin
db90: 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20  g.** on whether 
dba0: 6f 72 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20  or not the file 
dbb0: 68 61 73 20 62 65 65 6e 20 72 65 6e 61 6d 65 64  has been renamed
dbc0: 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65  , moved, or dele
dbd0: 74 65 64 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20  ted since it.** 
dbe0: 77 61 73 20 66 69 72 73 74 20 6f 70 65 6e 65 64  was first opened
dbf0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
dc00: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
dc10: 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a  _SET_HANDLE]].**
dc20: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
dc30: 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e  TL_WIN32_SET_HAN
dc40: 44 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  DLE] opcode is u
dc50: 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e  sed for debuggin
dc60: 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  g.  This.** opco
dc70: 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46  de causes the xF
dc80: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
dc90: 64 20 74 6f 20 73 77 61 70 20 74 68 65 20 66 69  d to swap the fi
dca0: 6c 65 20 68 61 6e 64 6c 65 20 77 69 74 68 20 74  le handle with t
dcb0: 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65  he one.** pointe
dcc0: 64 20 74 6f 20 62 79 20 74 68 65 20 70 41 72 67  d to by the pArg
dcd0: 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 69 73   argument.  This
dce0: 20 63 61 70 61 62 69 6c 69 74 79 20 69 73 20 75   capability is u
dcf0: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
dd00: 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e  ng.** and only n
dd10: 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f  eeds to be suppo
dd20: 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45  rted when SQLITE
dd30: 5f 54 45 53 54 20 69 73 20 64 65 66 69 6e 65 64  _TEST is defined
dd40: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
dd50: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42  LITE_FCNTL_WAL_B
dd60: 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  LOCK]].** The [S
dd70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f  QLITE_FCNTL_WAL_
dd80: 42 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69 67 6e  BLOCK] is a sign
dd90: 61 6c 20 74 6f 20 74 68 65 20 56 46 53 20 6c 61  al to the VFS la
dda0: 79 65 72 20 74 68 61 74 20 69 74 20 6d 69 67 68  yer that it migh
ddb0: 74 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74 61 67  t.** be advantag
ddc0: 65 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e  eous to block on
ddd0: 20 74 68 65 20 6e 65 78 74 20 57 41 4c 20 6c 6f   the next WAL lo
dde0: 63 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b 20 69  ck if the lock i
ddf0: 73 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74 65 6c  s not immediatel
de00: 79 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65 2e 20  y.** available. 
de10: 20 54 68 65 20 57 41 4c 20 73 75 62 73 79 73 74   The WAL subsyst
de20: 65 6d 20 69 73 73 75 65 73 20 74 68 69 73 20 73  em issues this s
de30: 69 67 6e 61 6c 20 64 75 72 69 6e 67 20 72 61 72  ignal during rar
de40: 65 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61 6e 63  e.** circumstanc
de50: 65 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  es in order to f
de60: 69 78 20 61 20 70 72 6f 62 6c 65 6d 20 77 69 74  ix a problem wit
de70: 68 20 70 72 69 6f 72 69 74 79 20 69 6e 76 65 72  h priority inver
de80: 73 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  sion..** Applica
de90: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c 65 6d  tions should <em
dea0: 3e 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20 74 68  >not</em> use th
deb0: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e  is file-control.
dec0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
ded0: 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53  ITE_FCNTL_ZIPVFS
dee0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
def0: 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 20  E_FCNTL_ZIPVFS] 
df00: 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d  opcode is implem
df10: 65 6e 74 65 64 20 62 79 20 7a 69 70 76 66 73 20  ented by zipvfs 
df20: 6f 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65 72 0a  only. All other.
df30: 2a 2a 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65  ** VFS should re
df40: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46  turn SQLITE_NOTF
df50: 4f 55 4e 44 20 66 6f 72 20 74 68 69 73 20 6f 70  OUND for this op
df60: 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  code..**.** <li>
df70: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52  [[SQLITE_FCNTL_R
df80: 42 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  BU]].** The [SQL
df90: 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 20 6f  ITE_FCNTL_RBU] o
dfa0: 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65  pcode is impleme
dfb0: 6e 74 65 64 20 62 79 20 74 68 65 20 73 70 65 63  nted by the spec
dfc0: 69 61 6c 20 56 46 53 20 75 73 65 64 20 62 79 0a  ial VFS used by.
dfd0: 2a 2a 20 74 68 65 20 52 42 55 20 65 78 74 65 6e  ** the RBU exten
dfe0: 73 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20  sion only.  All 
dff0: 6f 74 68 65 72 20 56 46 53 20 73 68 6f 75 6c 64  other VFS should
e000: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e   return SQLITE_N
e010: 4f 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a 20 74  OTFOUND for.** t
e020: 68 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a  his opcode.  .**
e030: 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </ul>.*/.#defin
e040: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  e SQLITE_FCNTL_L
e050: 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20  OCKSTATE        
e060: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
e070: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45   SQLITE_FCNTL_GE
e080: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
e090: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
e0a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54  SQLITE_FCNTL_SET
e0b0: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
e0c0: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
e0d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54  QLITE_FCNTL_LAST
e0e0: 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20  _ERRNO          
e0f0: 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
e100: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
e110: 48 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  HINT            
e120: 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c     5.#define SQL
e130: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
e140: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  SIZE            
e150: 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    6.#define SQLI
e160: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
e170: 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20  INTER           
e180: 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   7.#define SQLIT
e190: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
e1a0: 54 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20  TTED            
e1b0: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
e1c0: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
e1d0: 52 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39  RETRY          9
e1e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e1f0: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41  FCNTL_PERSIST_WA
e200: 4c 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a  L            10.
e210: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
e220: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20  CNTL_OVERWRITE  
e230: 20 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23              11.#
e240: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
e250: 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20  NTL_VFSNAME     
e260: 20 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64             12.#d
e270: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
e280: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  TL_POWERSAFE_OVE
e290: 52 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65  RWRITE    13.#de
e2a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
e2b0: 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20  L_PRAGMA        
e2c0: 20 20 20 20 20 20 20 20 20 31 34 0a 23 64 65 66           14.#def
e2d0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
e2e0: 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20  _BUSYHANDLER    
e2f0: 20 20 20 20 20 20 20 20 31 35 0a 23 64 65 66 69          15.#defi
e300: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
e310: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20  TEMPFILENAME    
e320: 20 20 20 20 20 20 20 31 36 0a 23 64 65 66 69 6e         16.#defin
e330: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d  e SQLITE_FCNTL_M
e340: 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20 20  MAP_SIZE        
e350: 20 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e 65        18.#define
e360: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52   SQLITE_FCNTL_TR
e370: 41 43 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ACE             
e380: 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65 20       19.#define 
e390: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53  SQLITE_FCNTL_HAS
e3a0: 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20 20  _MOVED          
e3b0: 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20 53      20.#define S
e3c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
e3d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
e3e0: 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53 51     21.#define SQ
e3f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
e400: 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20 20  T_PHASETWO      
e410: 20 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51 4c    22.#define SQL
e420: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
e430: 53 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20  SET_HANDLE      
e440: 20 32 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   23.#define SQLI
e450: 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f  TE_FCNTL_WAL_BLO
e460: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CK              
e470: 32 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  24.#define SQLIT
e480: 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 20 20  E_FCNTL_ZIPVFS  
e490: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
e4a0: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
e4b0: 5f 46 43 4e 54 4c 5f 52 42 55 20 20 20 20 20 20  _FCNTL_RBU      
e4c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 36                26
e4d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e4e0: 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45  FCNTL_VFS_POINTE
e4f0: 52 20 20 20 20 20 20 20 20 20 20 20 20 32 37 0a  R            27.
e500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
e510: 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49  CNTL_JOURNAL_POI
e520: 4e 54 45 52 20 20 20 20 20 20 20 20 32 38 0a 0a  NTER        28..
e530: 2f 2a 20 64 65 70 72 65 63 61 74 65 64 20 6e 61  /* deprecated na
e540: 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  mes */.#define S
e550: 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52  QLITE_GET_LOCKPR
e560: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c  OXYFILE      SQL
e570: 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f  ITE_FCNTL_GET_LO
e580: 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66  CKPROXYFILE.#def
e590: 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c  ine SQLITE_SET_L
e5a0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
e5b0: 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53    SQLITE_FCNTL_S
e5c0: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
e5d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e5e0: 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20  LAST_ERRNO      
e5f0: 20 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43         SQLITE_FC
e600: 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a  NTL_LAST_ERRNO..
e610: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
e620: 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a   Mutex Handle.**
e630: 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f  .** The mutex mo
e640: 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69  dule within SQLi
e650: 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69  te defines [sqli
e660: 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65  te3_mutex] to be
e670: 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20   an.** abstract 
e680: 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78  type for a mutex
e690: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51   object.  The SQ
e6a0: 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20  Lite core never 
e6b0: 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20  looks.** at the 
e6c0: 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
e6d0: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73  ntation of an [s
e6e0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20  qlite3_mutex].  
e6f0: 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73  It only.** deals
e700: 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74   with pointers t
e710: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  o the [sqlite3_m
e720: 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  utex] object..**
e730: 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20  .** Mutexes are 
e740: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73  created using [s
e750: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
e760: 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  oc()]..*/.typede
e770: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
e780: 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d  _mutex sqlite3_m
e790: 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  utex;../*.** CAP
e7a0: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
e7b0: 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ace Object.**.**
e7c0: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
e7d0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
e7e0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
e7f0: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
e800: 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69  ween.** the SQLi
e810: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20  te core and the 
e820: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
e830: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68  ting system.  Th
e840: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68  e "vfs".** in th
e850: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62  e name of the ob
e860: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20  ject stands for 
e870: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79  "virtual file sy
e880: 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74  stem".  See.** t
e890: 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f  he [VFS | VFS do
e8a0: 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
e8b0: 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61   further informa
e8c0: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
e8d0: 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65  value of the iVe
e8e0: 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69  rsion field is i
e8f0: 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d  nitially 1 but m
e900: 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a  ay be larger in.
e910: 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  ** future versio
e920: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41  ns of SQLite.  A
e930: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
e940: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
e950: 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65   to this.** obje
e960: 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72  ct when the iVer
e970: 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e  sion value is in
e980: 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74  creased.  Note t
e990: 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72  hat the structur
e9a0: 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  e.** of the sqli
e9b0: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63  te3_vfs object c
e9c0: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72  hanges in the tr
e9d0: 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65  ansaction betwee
e9e0: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  n.** SQLite vers
e9f0: 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e  ion 3.5.9 and 3.
ea00: 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20  6.0 and yet the 
ea10: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77  iVersion field w
ea20: 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69  as not.** modifi
ea30: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a  ed..**.** The sz
ea40: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20  OsFile field is 
ea50: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
ea60: 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69  subclassed [sqli
ea70: 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72  te3_file].** str
ea80: 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74  ucture used by t
ea90: 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68  his VFS.  mxPath
eaa0: 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69  name is the maxi
eab0: 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a  mum length of.**
eac0: 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74   a pathname in t
ead0: 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52  his VFS..**.** R
eae0: 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65  egistered sqlite
eaf0: 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72  3_vfs objects ar
eb00: 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b  e kept on a link
eb10: 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62  ed list formed b
eb20: 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70  y.** the pNext p
eb30: 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71  ointer.  The [sq
eb40: 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74  lite3_vfs_regist
eb50: 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  er()].** and [sq
eb60: 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69  lite3_vfs_unregi
eb70: 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  ster()] interfac
eb80: 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c  es manage this l
eb90: 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65  ist.** in a thre
eba0: 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68  ad-safe way.  Th
ebb0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66  e [sqlite3_vfs_f
ebc0: 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ind()] interface
ebd0: 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65  .** searches the
ebe0: 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20   list.  Neither 
ebf0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
ec00: 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53  code nor the VFS
ec10: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
ec20: 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68  on should use th
ec30: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
ec40: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74  .**.** The pNext
ec50: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e   field is the on
ec60: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20  ly field in the 
ec70: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73  sqlite3_vfs.** s
ec80: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51  tructure that SQ
ec90: 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d  Lite will ever m
eca0: 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77  odify.  SQLite w
ecb0: 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a  ill only access.
ecc0: 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ** or modify thi
ecd0: 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f  s field while ho
ece0: 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c  lding a particul
ecf0: 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e  ar static mutex.
ed00: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
ed10: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
ed20: 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67   modify anything
ed30: 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69   within the sqli
ed40: 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63  te3_vfs.** objec
ed50: 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63  t once the objec
ed60: 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73  t has been regis
ed70: 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tered..**.** The
ed80: 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c   zName field hol
ed90: 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ds the name of t
eda0: 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20  he VFS module.  
edb0: 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a  The name must.**
edc0: 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73   be unique acros
edd0: 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65  s all VFS module
ede0: 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74  s..**.** [[sqlit
edf0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a  e3_vfs.xOpen]].*
ee00: 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e  * ^SQLite guaran
ee10: 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46  tees that the zF
ee20: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
ee30: 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73  r to xOpen.** is
ee40: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
ee50: 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67  ointer or string
ee60: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
ee70: 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28  m xFullPathname(
ee80: 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e  ) with an option
ee90: 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e  al suffix added.
eea0: 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78  .** ^If a suffix
eeb0: 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65   is added to the
eec0: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
eed0: 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a  eter, it will.**
eee0: 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69   consist of a si
eef0: 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74  ngle "-" charact
ef00: 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e  er followed by n
ef10: 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31  o more than.** 1
ef20: 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61  1 alphanumeric a
ef30: 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63  nd/or "-" charac
ef40: 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  ters..** ^SQLite
ef50: 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74   further guarant
ef60: 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ees that.** the 
ef70: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76  string will be v
ef80: 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67  alid and unchang
ef90: 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28  ed until xClose(
efa0: 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20  ) is.** called. 
efb0: 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  Because of the p
efc0: 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
efd0: 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  ,.** the [sqlite
efe0: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65  3_file] can safe
eff0: 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74  ly store a point
f000: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c  er to the.** fil
f010: 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64  ename if it need
f020: 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68  s to remember th
f030: 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73  e filename for s
f040: 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49  ome reason..** I
f050: 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  f the zFilename 
f060: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
f070: 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  en is a NULL poi
f080: 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a  nter then xOpen.
f090: 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69  ** must invent i
f0a0: 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79  ts own temporary
f0b0: 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69   name for the fi
f0c0: 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74  le.  ^Whenever t
f0d0: 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65  he .** xFilename
f0e0: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55   parameter is NU
f0f0: 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20  LL it will also 
f100: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
f110: 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61   the.** flags pa
f120: 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63  rameter will inc
f130: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
f140: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
f150: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
f160: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  s argument to xO
f170: 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61  pen() includes a
f180: 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a  ll bits set in.*
f190: 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75  * the flags argu
f1a0: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
f1b0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72  _open_v2()].  Or
f1c0: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   if [sqlite3_ope
f1d0: 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  n()].** or [sqli
f1e0: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73  te3_open16()] is
f1f0: 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67   used, then flag
f200: 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65  s includes at le
f210: 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ast.** [SQLITE_O
f220: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
f230: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
f240: 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f  EATE]. .** If xO
f250: 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69  pen() opens a fi
f260: 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65  le read-only the
f270: 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46  n it sets *pOutF
f280: 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75  lags to.** inclu
f290: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
f2a0: 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65  READONLY].  Othe
f2b0: 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46  r bits in *pOutF
f2c0: 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e  lags may be set.
f2d0: 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20  .**.** ^(SQLite 
f2e0: 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e  will also add on
f2f0: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
f300: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
f310: 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c  xOpen().** call,
f320: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
f330: 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f  e object being o
f340: 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  pened:.**.** <ul
f350: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  >.** <li>  [SQLI
f360: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d  TE_OPEN_MAIN_DB]
f370: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
f380: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
f390: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
f3a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
f3b0: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
f3c0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
f3d0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
f3e0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52   [SQLITE_OPEN_TR
f3f0: 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c  ANSIENT_DB].** <
f400: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
f410: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  N_SUBJOURNAL].**
f420: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
f430: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e  PEN_MASTER_JOURN
f440: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
f450: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a  LITE_OPEN_WAL].*
f460: 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
f470: 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70  The file I/O imp
f480: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20  lementation can 
f490: 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74  use the object t
f4a0: 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20  ype flags to.** 
f4b0: 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69  change the way i
f4c0: 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c  t deals with fil
f4d0: 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  es.  For example
f4e0: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
f4f0: 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  .** that does no
f500: 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61  t care about cra
f510: 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72  sh recovery or r
f520: 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61  ollback might ma
f530: 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f  ke.** the open o
f540: 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  f a journal file
f550: 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65   a no-op.  Write
f560: 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61  s to this journa
f570: 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20  l would.** also 
f580: 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61  be no-ops, and a
f590: 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65  ny attempt to re
f5a0: 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77  ad the journal w
f5b0: 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53  ould return.** S
f5c0: 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72  QLITE_IOERR.  Or
f5d0: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
f5e0: 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e  ion might recogn
f5f0: 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62  ize that a datab
f600: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c  ase.** file will
f610: 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61   be doing page-a
f620: 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65  ligned sector re
f630: 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69  ads and writes i
f640: 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72  n a random.** or
f650: 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69  der and set up i
f660: 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d  ts I/O subsystem
f670: 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a   accordingly..**
f680: 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74  .** SQLite might
f690: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
f6a0: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
f6b0: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
f6c0: 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  n method:.**.** 
f6d0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
f6e0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
f6f0: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e  ONCLOSE].** <li>
f700: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
f710: 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c  CLUSIVE].** </ul
f720: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  >.**.** The [SQL
f730: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
f740: 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61  NCLOSE] flag mea
f750: 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  ns the file shou
f760: 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64  ld be.** deleted
f770: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73   when it is clos
f780: 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  ed.  ^The [SQLIT
f790: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
f7a0: 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65  LOSE].** will be
f7b0: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61   set for TEMP da
f7c0: 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69  tabases and thei
f7d0: 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e  r journals, tran
f7e0: 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73  sient.** databas
f7f0: 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e  es, and subjourn
f800: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  als..**.** ^The 
f810: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
f820: 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20  LUSIVE] flag is 
f830: 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63  always used in c
f840: 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69  onjunction.** wi
f850: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
f860: 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67  PEN_CREATE] flag
f870: 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68  , which are both
f880: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61   directly.** ana
f890: 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f  logous to the O_
f8a0: 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54  EXCL and O_CREAT
f8b0: 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f   flags of the PO
f8c0: 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50  SIX open().** AP
f8d0: 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  I.  The SQLITE_O
f8e0: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c  PEN_EXCLUSIVE fl
f8f0: 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20  ag, when paired 
f900: 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c  with the .** SQL
f910: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c  ITE_OPEN_CREATE,
f920: 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69   is used to indi
f930: 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73  cate that file s
f940: 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20  hould always.** 
f950: 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20  be created, and 
f960: 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72  that it is an er
f970: 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64  ror if it alread
f980: 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20  y exists..** It 
f990: 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73  is <i>not</i> us
f9a0: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ed to indicate t
f9b0: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
f9c0: 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72  e opened .** for
f9d0: 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73   exclusive acces
f9e0: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61  s..**.** ^At lea
f9f0: 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65  st szOsFile byte
fa00: 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20  s of memory are 
fa10: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c  allocated by SQL
fa20: 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74  ite.** to hold t
fa30: 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  he  [sqlite3_fil
fa40: 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73  e] structure pas
fa50: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
fa60: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
fa70: 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65  xOpen.  The xOpe
fa80: 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f  n method does no
fa90: 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c  t have to.** all
faa0: 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74  ocate the struct
fab0: 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a  ure; it should j
fac0: 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20  ust fill it in. 
fad0: 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68   Note that.** th
fae0: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d  e xOpen method m
faf0: 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69  ust set the sqli
fb00: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
fb10: 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61  s to either.** a
fb20: 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f   valid [sqlite3_
fb30: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
fb40: 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20  ct or to NULL.  
fb50: 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a  xOpen must do.**
fb60: 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68   this even if th
fb70: 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53  e open fails.  S
fb80: 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68  QLite expects th
fb90: 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  at the sqlite3_f
fba0: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20  ile.pMethods.** 
fbb0: 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  element will be 
fbc0: 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65  valid after xOpe
fbd0: 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64  n returns regard
fbe0: 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63  less of the succ
fbf0: 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72  ess.** or failur
fc00: 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63  e of the xOpen c
fc10: 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c  all..**.** [[sql
fc20: 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73  ite3_vfs.xAccess
fc30: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73  ]].** ^The flags
fc40: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63   argument to xAc
fc50: 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53  cess() may be [S
fc60: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
fc70: 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  STS].** to test 
fc80: 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63  for the existenc
fc90: 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20  e of a file, or 
fca0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
fcb0: 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20  EADWRITE] to.** 
fcc0: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66  test whether a f
fcd0: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20  ile is readable 
fce0: 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72  and writable, or
fcf0: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
fd00: 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  READ].** to test
fd10: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
fd20: 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64  is at least read
fd30: 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65  able.   The file
fd40: 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72   can be a.** dir
fd50: 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53  ectory..**.** ^S
fd60: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79  QLite will alway
fd70: 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65  s allocate at le
fd80: 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31  ast mxPathname+1
fd90: 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a   bytes for the.*
fda0: 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20  * output buffer 
fdb0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20  xFullPathname.  
fdc0: 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f  The exact size o
fdd0: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
fde0: 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70  fer.** is also p
fdf0: 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d  assed as a param
fe00: 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65  eter to both  me
fe10: 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75  thods. If the ou
fe20: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
fe30: 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75  s not large enou
fe40: 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54  gh, [SQLITE_CANT
fe50: 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20  OPEN] should be 
fe60: 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20  returned. Since 
fe70: 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c  this is.** handl
fe80: 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72  ed as a fatal er
fe90: 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76  ror by SQLite, v
fea0: 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  fs implementatio
feb0: 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76  ns should endeav
fec0: 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74  or.** to prevent
fed0: 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67   this by setting
fee0: 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61   mxPathname to a
fef0: 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61   sufficiently la
ff00: 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  rge value..**.**
ff10: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
ff20: 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43  (), xSleep(), xC
ff30: 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e  urrentTime(), an
ff40: 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  d xCurrentTimeIn
ff50: 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  t64().** interfa
ff60: 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69  ces are not stri
ff70: 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74  ctly a part of t
ff80: 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62  he filesystem, b
ff90: 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69  ut they are.** i
ffa0: 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56  ncluded in the V
ffb0: 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72  FS structure for
ffc0: 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a   completeness..*
ffd0: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
ffe0: 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74  s() function att
fff0: 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20  empts to return 
10000 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20  nBytes bytes.** 
10010 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20  of good-quality 
10020 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
10030 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72  zOut.  The retur
10040 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68  n value is.** th
10050 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20  e actual number 
10060 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64  of bytes of rand
10070 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e  omness obtained.
10080 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29  .** The xSleep()
10090 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74   method causes t
100a0 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61  he calling threa
100b0 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61  d to sleep for a
100c0 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e  t.** least the n
100d0 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65  umber of microse
100e0 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54  conds given.  ^T
100f0 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  he xCurrentTime(
10100 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
10110 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79  rns a Julian Day
10120 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20   Number for the 
10130 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64  current date and
10140 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c   time as.** a fl
10150 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
10160 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72  ue..** ^The xCur
10170 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
10180 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20  method returns, 
10190 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  as an integer, t
101a0 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79  he Julian.** Day
101b0 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69   Number multipli
101c0 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28  ed by 86400000 (
101d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  the number of mi
101e0 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a  lliseconds in .*
101f0 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29  * a 24-hour day)
10200 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .  .** ^SQLite w
10210 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72  ill use the xCur
10220 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
10230 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68  method to get th
10240 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74  e current.** dat
10250 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68  e and time if th
10260 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61  at method is ava
10270 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73  ilable (if iVers
10280 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20  ion is 2 or .** 
10290 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20  greater and the 
102a0 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
102b0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e   is not NULL) an
102c0 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b  d will fall back
102d0 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54  .** to xCurrentT
102e0 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e  ime() if xCurren
102f0 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20  tTimeInt64() is 
10300 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a  unavailable..**.
10310 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74  ** ^The xSetSyst
10320 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79  emCall(), xGetSy
10330 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20  stemCall(), and 
10340 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28  xNestSystemCall(
10350 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
10360 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20  are not used by 
10370 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e  the SQLite core.
10380 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c    These optional
10390 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
103a0 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73  provided.** by s
103b0 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63  ome VFSes to fac
103c0 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20  ilitate testing 
103d0 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e  of the VFS code.
103e0 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a   By overriding .
103f0 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  ** system calls 
10400 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75  with functions u
10410 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c  nder its control
10420 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d  , a test program
10430 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65   can.** simulate
10440 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f   faults and erro
10450 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61  r conditions tha
10460 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73  t would otherwis
10470 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a  e be difficult.*
10480 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20  * or impossible 
10490 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20  to induce.  The 
104a0 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61  set of system ca
104b0 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  lls that can be 
104c0 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61  overridden.** va
104d0 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46  ries from one VF
104e0 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e  S to another, an
104f0 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69  d from one versi
10500 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56  on of the same V
10510 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78  FS to the.** nex
10520 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  t.  Applications
10530 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20   that use these 
10540 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20  interfaces must 
10550 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20  be prepared for 
10560 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66  any.** or all of
10570 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
10580 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20  s to be NULL or 
10590 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69  for their behavi
105a0 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  or to change.** 
105b0 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65  from one release
105c0 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41   to the next.  A
105d0 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74  pplications must
105e0 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20   not attempt to 
105f0 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66  access.** any of
10600 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69   these methods i
10610 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f  f the iVersion o
10620 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73  f the VFS is les
10630 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70  s than 3..*/.typ
10640 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
10650 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f  te3_vfs sqlite3_
10660 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69  vfs;.typedef voi
10670 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63  d (*sqlite3_sysc
10680 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a  all_ptr)(void);.
10690 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
106a0 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  fs {.  int iVers
106b0 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  ion;            
106c0 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72  /* Structure ver
106d0 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72  sion number (cur
106e0 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69  rently 3) */.  i
106f0 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20  nt szOsFile;    
10700 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20          /* Size 
10710 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71  of subclassed sq
10720 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20  lite3_file */.  
10730 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20  int mxPathname; 
10740 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
10750 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  mum file pathnam
10760 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71  e length */.  sq
10770 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74  lite3_vfs *pNext
10780 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72  ;      /* Next r
10790 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f  egistered VFS */
107a0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
107b0 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e  Name;       /* N
107c0 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74  ame of this virt
107d0 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20  ual file system 
107e0 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
107f0 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ata;          /*
10800 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c   Pointer to appl
10810 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63  ication-specific
10820 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28   data */.  int (
10830 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  *xOpen)(sqlite3_
10840 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
10850 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
10860 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20  _file*,.        
10870 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73         int flags
10880 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73  , int *pOutFlags
10890 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65  );.  int (*xDele
108a0 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  te)(sqlite3_vfs*
108b0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
108c0 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72  ame, int syncDir
108d0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65  );.  int (*xAcce
108e0 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
108f0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
10900 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20  ame, int flags, 
10910 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
10920 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68   int (*xFullPath
10930 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  name)(sqlite3_vf
10940 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
10950 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c  zName, int nOut,
10960 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
10970 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29  void *(*xDlOpen)
10980 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
10990 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
109a0 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a  name);.  void (*
109b0 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65  xDlError)(sqlite
109c0 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
109d0 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67  e, char *zErrMsg
109e0 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44  );.  void (*(*xD
109f0 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66  lSym)(sqlite3_vf
10a00 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20  s*,void*, const 
10a10 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28  char *zSymbol))(
10a20 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a  void);.  void (*
10a30 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  xDlClose)(sqlite
10a40 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a  3_vfs*, void*);.
10a50 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e    int (*xRandomn
10a60 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
10a70 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
10a80 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74  ar *zOut);.  int
10a90 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74   (*xSleep)(sqlit
10aa0 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63  e3_vfs*, int mic
10ab0 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e  roseconds);.  in
10ac0 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
10ad0 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
10ae0 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  double*);.  int 
10af0 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29  (*xGetLastError)
10b00 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
10b10 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f  nt, char *);.  /
10b20 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
10b30 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
10b40 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65  version 1 of the
10b50 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
10b60 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69  ct.  ** definiti
10b70 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20  on.  Those that 
10b80 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64  follow are added
10b90 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72   in version 2 or
10ba0 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e   later.  */.  in
10bb0 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
10bc0 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76  Int64)(sqlite3_v
10bd0 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  fs*, sqlite3_int
10be0 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  64*);.  /*.  ** 
10bf0 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
10c00 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
10c10 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65  s 1 and 2 of the
10c20 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
10c30 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62  ct..  ** Those b
10c40 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72  elow are for ver
10c50 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74  sion 3 and great
10c60 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28  er..  */.  int (
10c70 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xSetSystemCall)
10c80 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
10c90 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
10ca0 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c  , sqlite3_syscal
10cb0 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65  l_ptr);.  sqlite
10cc0 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a  3_syscall_ptr (*
10cd0 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  xGetSystemCall)(
10ce0 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
10cf0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
10d00 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ;.  const char *
10d10 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c  (*xNextSystemCal
10d20 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
10d30 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
10d40 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  me);.  /*.  ** T
10d50 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
10d60 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
10d70 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20   1 through 3 of 
10d80 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f  the sqlite_vfs o
10d90 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20  bject..  ** New 
10da0 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
10db0 70 65 6e 64 65 64 20 69 6e 20 66 75 74 75 72 65  pended in future
10dc0 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20   versions.  The 
10dd0 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61  iVersion.  ** va
10de0 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65  lue will increme
10df0 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73  nt whenever this
10e00 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a   happens. .  */.
10e10 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
10e20 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
10e30 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65  e xAccess VFS me
10e40 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  thod.**.** These
10e50 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
10e60 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61  ts can be used a
10e70 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  s the third para
10e80 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  meter to.** the 
10e90 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f  xAccess method o
10ea0 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  f an [sqlite3_vf
10eb0 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79  s] object.  They
10ec0 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68   determine.** wh
10ed0 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69  at kind of permi
10ee0 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65  ssions the xAcce
10ef0 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f  ss method is loo
10f00 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74  king for..** Wit
10f10 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
10f20 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63  EXISTS, the xAcc
10f30 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69  ess method.** si
10f40 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74  mply checks whet
10f50 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69  her the file exi
10f60 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  sts..** With SQL
10f70 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
10f80 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73  RITE, the xAcces
10f90 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
10fa0 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e  ks whether the n
10fb0 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69  amed directory i
10fc0 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20  s both readable 
10fd0 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20  and writable.** 
10fe0 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c  (in other words,
10ff0 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65   if files can be
11000 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c   added, removed,
11010 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74   and renamed wit
11020 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63  hin.** the direc
11030 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51  tory)..** The SQ
11040 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
11050 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69  WRITE constant i
11060 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64  s currently used
11070 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20   only by the.** 
11080 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
11090 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74  ctory pragma], t
110a0 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64  hough this could
110b0 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74   change in a fut
110c0 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f  ure.** release o
110d0 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74  f SQLite..** Wit
110e0 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
110f0 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73  READ, the xAcces
11100 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
11110 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
11120 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e  ile is readable.
11130 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43    The SQLITE_ACC
11140 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e  ESS_READ constan
11150 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c  t is.** currentl
11160 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68  y unused, though
11170 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65   it might be use
11180 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65  d in a future re
11190 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69  lease of.** SQLi
111a0 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
111b0 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
111c0 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65  STS    0.#define
111d0 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
111e0 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20  EADWRITE 1   /* 
111f0 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74  Used by PRAGMA t
11200 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
11210 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ory */.#define S
11220 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
11230 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e  D      2   /* Un
11240 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  used */../*.** C
11250 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66  API3REF: Flags f
11260 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  or the xShmLock 
11270 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
11280 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
11290 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
112a0 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b  the various lock
112b0 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a  ing operations.*
112c0 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65  * allowed by the
112d0 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
112e0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   of [sqlite3_io_
112f0 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a  methods].  The.*
11300 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20  * following are 
11310 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63  the only legal c
11320 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66  ombinations of f
11330 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  lags to the.** x
11340 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a  ShmLock method:.
11350 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
11360 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  i>  SQLITE_SHM_L
11370 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
11380 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
11390 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
113a0 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58   | SQLITE_SHM_EX
113b0 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20  CLUSIVE.** <li> 
113c0 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
113d0 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
113e0 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20  SHARED.** <li>  
113f0 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
11400 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
11410 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c  XCLUSIVE.** </ul
11420 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c  >.**.** When unl
11430 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65  ocking, the same
11440 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55   SHARED or EXCLU
11450 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62  SIVE flag must b
11460 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a  e supplied as.**
11470 20 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74 68   was given on th
11480 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
11490 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68  lock.  .**.** Th
114a0 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
114b0 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e  d can transition
114c0 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65   between unlocke
114d0 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a  d and SHARED or.
114e0 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63  ** between unloc
114f0 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56  ked and EXCLUSIV
11500 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72  E.  It cannot tr
11510 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
11520 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45   SHARED.** and E
11530 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65  XCLUSIVE..*/.#de
11540 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
11550 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23  UNLOCK       1.#
11560 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
11570 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32  M_LOCK         2
11580 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
11590 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20  SHM_SHARED      
115a0 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
115b0 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20  E_SHM_EXCLUSIVE 
115c0 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     8../*.** CAPI
115d0 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53  3REF: Maximum xS
115e0 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a  hmLock index.**.
115f0 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20  ** The xShmLock 
11600 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74  method on [sqlit
11610 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d  e3_io_methods] m
11620 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a  ay use values.**
11630 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74   between 0 and t
11640 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20  his upper bound 
11650 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20  as its "offset" 
11660 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65  argument..** The
11670 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c   SQLite core wil
11680 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20  l never attempt 
11690 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65  to acquire or re
116a0 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20  lease a.** lock 
116b0 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20  outside of this 
116c0 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65  range.*/.#define
116d0 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43   SQLITE_SHM_NLOC
116e0 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a  K        8.../*.
116f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69  ** CAPI3REF: Ini
11700 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69  tialize The SQLi
11710 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
11720 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
11730 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
11740 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  ne initializes t
11750 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62  he.** SQLite lib
11760 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69  rary.  ^The sqli
11770 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72  te3_shutdown() r
11780 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f  outine.** deallo
11790 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72  cates any resour
117a0 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c  ces that were al
117b0 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
117c0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
117d0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
117e0 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20  es are designed 
117f0 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73  to aid in proces
11800 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  s initialization
11810 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e   and.** shutdown
11820 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73   on embedded sys
11830 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69  tems.  Workstati
11840 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  on applications 
11850 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20  using.** SQLite 
11860 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20  normally do not 
11870 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65  need to invoke e
11880 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72  ither of these r
11890 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41  outines..**.** A
118a0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
118b0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
118c0 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20   an "effective" 
118d0 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a  call if it is.**
118e0 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
118f0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
11900 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ze() is invoked 
11910 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74  during the lifet
11920 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72  ime of.** the pr
11930 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20  ocess, or if it 
11940 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  is the first tim
11950 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
11960 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
11970 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  d.** following a
11980 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
11990 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28  _shutdown().  ^(
119a0 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76  Only an effectiv
119b0 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c  e call.** of sql
119c0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
119d0 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69  ) does any initi
119e0 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20  alization.  All 
119f0 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61  other calls.** a
11a00 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
11a10 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ps.)^.**.** A ca
11a20 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
11a30 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22  utdown() is an "
11a40 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
11a50 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
11a60 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71  st.** call to sq
11a70 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
11a80 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20   since the last 
11a90 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
11aa0 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a  ze().  ^(Only.**
11ab0 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
11ac0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
11ad0 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e  utdown() does an
11ae0 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69  y deinitializati
11af0 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72  on..** All other
11b00 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20   valid calls to 
11b10 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
11b20 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20  () are harmless 
11b30 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  no-ops.)^.**.** 
11b40 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
11b50 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61  ialize() interfa
11b60 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  ce is threadsafe
11b70 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68  , but sqlite3_sh
11b80 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e  utdown().** is n
11b90 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ot.  The sqlite3
11ba0 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65  _shutdown() inte
11bb0 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20  rface must only 
11bc0 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  be called from a
11bd0 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61  .** single threa
11be0 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61  d.  All open [da
11bf0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11c00 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73  ns] must be clos
11c10 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74  ed and all.** ot
11c20 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75  her SQLite resou
11c30 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61  rces must be dea
11c40 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74  llocated prior t
11c50 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71  o invoking.** sq
11c60 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
11c70 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74  ..**.** Among ot
11c80 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c  her things, ^sql
11c90 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
11ca0 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a  ) will invoke.**
11cb0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
11cc0 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20  ().  Similarly, 
11cd0 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  ^sqlite3_shutdow
11ce0 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f  n().** will invo
11cf0 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  ke sqlite3_os_en
11d00 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  d()..**.** ^The 
11d10 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
11d20 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  ze() routine ret
11d30 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
11d40 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20   on success..** 
11d50 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ^If for some rea
11d60 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69  son, sqlite3_ini
11d70 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61  tialize() is una
11d80 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a  ble to initializ
11d90 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79  e.** the library
11da0 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20   (perhaps it is 
11db0 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
11dc0 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f  te a needed reso
11dd0 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20  urce such.** as 
11de0 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75  a mutex) it retu
11df0 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  rns an [error co
11e00 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  de] other than [
11e10 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
11e20 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
11e30 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
11e40 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e  ine is called in
11e50 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79  ternally by many
11e60 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
11e70 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74   interfaces so t
11e80 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69  hat an applicati
11e90 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20  on usually does 
11ea0 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69  not need to.** i
11eb0 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
11ec0 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
11ed0 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  tly.  For exampl
11ee0 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  e, [sqlite3_open
11ef0 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c  ()].** calls sql
11f00 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
11f10 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20  ) so the SQLite 
11f20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20  library will be 
11f30 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
11f40 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65   initialized whe
11f50 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  n [sqlite3_open(
11f60 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20  )] is called if 
11f70 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e  it has not be in
11f80 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72  itialized.** alr
11f90 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c  eady.  ^However,
11fa0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
11fb0 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20  mpiled with the 
11fc0 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
11fd0 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c  OINIT].** compil
11fe0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74  e-time option, t
11ff0 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69  hen the automati
12000 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  c calls to sqlit
12010 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a  e3_initialize().
12020 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61  ** are omitted a
12030 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  nd the applicati
12040 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c  on must call sql
12050 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
12060 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72  ) directly.** pr
12070 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79  ior to using any
12080 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
12090 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61  terface.  For ma
120a0 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74  ximum portabilit
120b0 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f  y,.** it is reco
120c0 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
120d0 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73  lications always
120e0 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
120f0 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20  initialize().** 
12100 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74  directly prior t
12110 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  o using any othe
12120 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
12130 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65  ce.  Future rele
12140 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ases.** of SQLit
12150 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68  e may require th
12160 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  is.  In other wo
12170 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f  rds, the behavio
12180 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77  r exhibited.** w
12190 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
121a0 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c  mpiled with [SQL
121b0 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
121c0 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20  T] might become 
121d0 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62  the.** default b
121e0 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20  ehavior in some 
121f0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
12200 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
12210 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
12220 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  nit() routine do
12230 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  es operating-sys
12240 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20  tem specific.** 
12250 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
12260 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  f the SQLite lib
12270 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74  rary.  The sqlit
12280 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72  e3_os_end().** r
12290 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68  outine undoes th
122a0 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69  e effect of sqli
122b0 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20  te3_os_init().  
122c0 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a  Typical tasks.**
122d0 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68   performed by th
122e0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63  ese routines inc
122f0 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  lude allocation 
12300 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a  or deallocation.
12310 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73  ** of static res
12320 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69  ources, initiali
12330 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c  zation of global
12340 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73   variables,.** s
12350 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61  etting up a defa
12360 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
12370 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74  ] module, or set
12380 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66  ting up.** a def
12390 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
123a0 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  on using [sqlite
123b0 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a  3_config()]..**.
123c0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
123d0 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
123e0 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71  invoke either sq
123f0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
12400 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  ** or sqlite3_os
12410 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e  _end() directly.
12420 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
12430 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e  n should only in
12440 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
12450 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
12460 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
12470 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65  n().  The sqlite
12480 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69  3_os_init().** i
12490 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c  nterface is call
124a0 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
124b0 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
124c0 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20  ialize() and.** 
124d0 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
124e0 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71   is called by sq
124f0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
12500 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a  .  Appropriate.*
12510 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
12520 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  s for sqlite3_os
12530 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69  _init() and sqli
12540 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
12550 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  are built into S
12560 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73  QLite when it is
12570 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e   compiled for Un
12580 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20  ix, Windows, or 
12590 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63  OS/2..** When [c
125a0 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62  ustom builds | b
125b0 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70  uilt for other p
125c0 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73  latforms].** (us
125d0 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
125e0 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70  OS_OTHER=1] comp
125f0 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
12600 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74  on) the applicat
12610 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20  ion must supply 
12620 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65  a suitable imple
12630 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a  mentation for.**
12640 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
12650 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
12660 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70  s_end().  An app
12670 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65  lication-supplie
12680 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  d.** implementat
12690 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  ion of sqlite3_o
126a0 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69  s_init() or sqli
126b0 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
126c0 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c  must return [SQL
126d0 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
126e0 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65  ss and some othe
126f0 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75  r [error code] u
12700 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a  pon.** failure..
12710 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
12720 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
12730 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
12740 69 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  ize(void);.SQLIT
12750 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
12760 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
12770 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b  _shutdown(void);
12780 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
12790 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
127a0 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76  qlite3_os_init(v
127b0 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
127c0 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
127d0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  ALL sqlite3_os_e
127e0 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  nd(void);../*.**
127f0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
12800 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74  guring The SQLit
12810 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20  e Library.**.** 
12820 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
12830 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
12840 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67  s used to make g
12850 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74  lobal configurat
12860 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
12870 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65  o SQLite in orde
12880 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65  r to tune SQLite
12890 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63   to the specific
128a0 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65   needs of.** the
128b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54   application.  T
128c0 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69  he default confi
128d0 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f  guration is reco
128e0 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74  mmended for most
128f0 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
12900 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75   and so this rou
12910 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20  tine is usually 
12920 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20  not necessary.  
12930 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65  It is.** provide
12940 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72  d to support rar
12950 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77  e applications w
12960 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64  ith unusual need
12970 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20  s..**.** <b>The 
12980 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12990 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
129a0 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 54 68  t threadsafe. Th
129b0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
129c0 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61   must ensure tha
129d0 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  t no other SQLit
129e0 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
129f0 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65   invoked by othe
12a00 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69  r.** threads whi
12a10 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  le sqlite3_confi
12a20 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 3c  g() is running.<
12a30 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  /b>.**.** The sq
12a40 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
12a50 6e 74 65 72 66 61 63 65 0a 2a 2a 20 6d 61 79 20  nterface.** may 
12a60 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20  only be invoked 
12a70 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79  prior to library
12a80 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
12a90 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
12aa0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
12ab0 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77  or after shutdow
12ac0 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68  n by [sqlite3_sh
12ad0 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49  utdown()]..** ^I
12ae0 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  f sqlite3_config
12af0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74  () is called aft
12b00 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  er [sqlite3_init
12b10 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65  ialize()] and be
12b20 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  fore.** [sqlite3
12b30 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65  _shutdown()] the
12b40 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e  n it will return
12b50 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a   SQLITE_MISUSE..
12b60 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72  ** Note, however
12b70 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f  , that ^sqlite3_
12b80 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20  config() can be 
12b90 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f  called as part o
12ba0 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  f the.** impleme
12bb0 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70  ntation of an ap
12bc0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
12bd0 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  d [sqlite3_os_in
12be0 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  it()]..**.** The
12bf0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
12c00 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  to sqlite3_confi
12c10 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65  g() is an intege
12c20 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74  r.** [configurat
12c30 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74  ion option] that
12c40 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77   determines.** w
12c50 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20  hat property of 
12c60 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20  SQLite is to be 
12c70 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62  configured.  Sub
12c80 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
12c90 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64  s.** vary depend
12ca0 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66  ing on the [conf
12cb0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
12cc0 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73  ].** in the firs
12cd0 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  t argument..**.*
12ce0 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67  * ^When a config
12cf0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
12d00 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63  s set, sqlite3_c
12d10 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20  onfig() returns 
12d20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20  [SQLITE_OK]..** 
12d30 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69  ^If the option i
12d40 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c  s unknown or SQL
12d50 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
12d60 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a   set the option.
12d70 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75  ** then this rou
12d80 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e  tine returns a n
12d90 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
12da0 6f 64 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ode]..*/.SQLITE_
12db0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 43  API int SQLITE_C
12dc0 44 45 43 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  DECL sqlite3_con
12dd0 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a  fig(int, ...);..
12de0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
12df0 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61  Configure databa
12e00 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  se connections.*
12e10 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
12e20 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  3.**.** The sqli
12e30 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
12e40 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
12e50 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67  d to make config
12e60 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
12e70 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73  es to a [databas
12e80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
12e90 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73  The interface is
12ea0 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b   similar to.** [
12eb0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12ec0 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68  ] except that th
12ed0 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20  e changes apply 
12ee0 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b  to a single.** [
12ef0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12f00 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20  ion] (specified 
12f10 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
12f20 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  ument)..**.** Th
12f30 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
12f40 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f  t to sqlite3_db_
12f50 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20  config(D,V,...) 
12f60 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   is the.** [SQLI
12f70 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
12f80 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72  ASIDE | configur
12f90 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e  ation verb] - an
12fa0 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a   integer code .*
12fb0 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73  * that indicates
12fc0 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 20   what aspect of 
12fd0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
12fe0 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69  nnection] is bei
12ff0 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a  ng configured..*
13000 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67  * Subsequent arg
13010 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 65  uments vary depe
13020 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e  nding on the con
13030 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e  figuration verb.
13040 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f  .**.** ^Calls to
13050 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
13060 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49  ig() return SQLI
13070 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c  TE_OK if and onl
13080 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  y if.** the call
13090 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73   is considered s
130a0 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51  uccessful..*/.SQ
130b0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
130c0 49 54 45 5f 43 44 45 43 4c 20 73 71 6c 69 74 65  ITE_CDECL sqlite
130d0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69  3_db_config(sqli
130e0 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e  te3*, int op, ..
130f0 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
13100 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
13110 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a  cation Routines.
13120 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
13130 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
13140 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
13150 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53  erface between S
13160 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77  QLite.** and low
13170 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
13180 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
13190 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62  s..**.** This ob
131a0 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20  ject is used in 
131b0 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69  only one place i
131c0 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74  n the SQLite int
131d0 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69  erface..** A poi
131e0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
131f0 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
13200 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  ct is the argume
13210 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  nt to.** [sqlite
13220 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e  3_config()] when
13230 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
13240 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  on option is.** 
13250 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
13260 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54  ALLOC] or [SQLIT
13270 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
13280 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65  OC].  .** By cre
13290 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63  ating an instanc
132a0 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
132b0 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20  .** and passing 
132c0 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
132d0 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
132e0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a  ONFIG_MALLOC]).*
132f0 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75  * during configu
13300 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69  ration, an appli
13310 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69  cation can speci
13320 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
13330 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
13340 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
13350 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75   for SQLite to u
13360 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  se for all of it
13370 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d  s.** dynamic mem
13380 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ory needs..**.**
13390 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74   Note that SQLit
133a0 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76  e comes with sev
133b0 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d  eral [built-in m
133c0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
133d0 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65  ].** that are pe
133e0 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65  rfectly adequate
133f0 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65   for the overwhe
13400 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f  lming majority o
13410 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
13420 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  * and that this 
13430 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75  object is only u
13440 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20  seful to a tiny 
13450 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  minority of appl
13460 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68  ications.** with
13470 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d   specialized mem
13480 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
13490 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68  equirements.  Th
134a0 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20  is object is.** 
134b0 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67  also used during
134c0 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69   testing of SQLi
134d0 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73  te in order to s
134e0 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
134f0 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
13500 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73  allocator that s
13510 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20  imulates memory 
13520 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f  out-of-memory co
13530 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f  nditions in.** o
13540 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74  rder to verify t
13550 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76  hat SQLite recov
13560 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66  ers gracefully f
13570 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64  rom such.** cond
13580 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  itions..**.** Th
13590 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c  e xMalloc, xReal
135a0 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d  loc, and xFree m
135b0 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b  ethods must work
135c0 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c   like the.** mal
135d0 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29  loc(), realloc()
135e0 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63   and free() func
135f0 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73  tions from the s
13600 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
13610 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  y..** ^SQLite gu
13620 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
13630 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
13640 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63  t to.** xRealloc
13650 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c   is always a val
13660 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61  ue returned by a
13670 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78   prior call to x
13680 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78  Roundup..**.** x
13690 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75  Size should retu
136a0 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  rn the allocated
136b0 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72   size of a memor
136c0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
136d0 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
136e0 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63  ned from xMalloc
136f0 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54   or xRealloc.  T
13700 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
13710 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  e.** is always a
13720 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61  t least as big a
13730 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  s the requested 
13740 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20  size but may be 
13750 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  larger..**.** Th
13760 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f  e xRoundup metho
13770 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77  d returns what w
13780 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f  ould be the allo
13790 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a  cated size of.**
137a0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
137b0 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72  tion given a par
137c0 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65  ticular requeste
137d0 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65  d size.  Most me
137e0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
137f0 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f  rs round up memo
13800 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61  ry allocations a
13810 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e  t least to the n
13820 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  ext multiple.** 
13830 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f  of 8.  Some allo
13840 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
13850 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74  to a larger mult
13860 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77  iple or to a pow
13870 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72  er of 2..** Ever
13880 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  y memory allocat
13890 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69  ion request comi
138a0 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73  ng in through [s
138b0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
138c0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
138d0 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74  realloc()] first
138e0 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e   calls xRoundup.
138f0 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65    If xRoundup re
13900 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61  turns 0, .** tha
13910 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72  t causes the cor
13920 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72  responding memor
13930 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
13940 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fail..**.** The 
13950 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69  xInit method ini
13960 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d  tializes the mem
13970 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20  ory allocator.  
13980 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  For example,.** 
13990 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74  it might allocat
139a0 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75  e any require mu
139b0 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c  texes or initial
139c0 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  ize internal dat
139d0 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e  a.** structures.
139e0 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20    The xShutdown 
139f0 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65  method is invoke
13a00 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62  d (indirectly) b
13a10 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  y.** [sqlite3_sh
13a20 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68  utdown()] and sh
13a30 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20  ould deallocate 
13a40 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63  any resources ac
13a50 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e  quired.** by xIn
13a60 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74  it.  The pAppDat
13a70 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65  a pointer is use
13a80 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  d as the only pa
13a90 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49  rameter to.** xI
13aa0 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77  nit and xShutdow
13ab0 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
13ac0 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54  holds the [SQLIT
13ad0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
13ae0 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65  ASTER] mutex whe
13af0 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20  n it invokes.** 
13b00 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  the xInit method
13b10 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d  , so the xInit m
13b20 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62  ethod need not b
13b30 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54  e threadsafe.  T
13b40 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20  he.** xShutdown 
13b50 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63  method is only c
13b60 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  alled from [sqli
13b70 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
13b80 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f  so it does.** no
13b90 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72  t need to be thr
13ba0 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20  eadsafe either. 
13bb0 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d   For all other m
13bc0 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a  ethods, SQLite.*
13bd0 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c  * holds the [SQL
13be0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
13bf0 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c  _MEM] mutex as l
13c00 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53  ong as the.** [S
13c10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
13c20 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72  STATUS] configur
13c30 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
13c40 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68  turned on (which
13c50 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66  .** it is by def
13c60 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65  ault) and so the
13c70 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74   methods are aut
13c80 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61  omatically seria
13c90 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65  lized..** Howeve
13ca0 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f  r, if [SQLITE_CO
13cb0 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
13cc0 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65  is disabled, the
13cd0 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d  n the other.** m
13ce0 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74  ethods must be t
13cf0 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73  hreadsafe or els
13d00 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e  e make their own
13d10 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f   arrangements fo
13d20 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69  r.** serializati
13d30 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  on..**.** SQLite
13d40 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f   will never invo
13d50 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20  ke xInit() more 
13d60 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75  than once withou
13d70 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67  t an intervening
13d80 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75  .** call to xShu
13d90 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65  tdown()..*/.type
13da0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
13db0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73  e3_mem_methods s
13dc0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
13dd0 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
13de0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b  e3_mem_methods {
13df0 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c  .  void *(*xMall
13e00 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  oc)(int);       
13e10 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f    /* Memory allo
13e20 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20  cation function 
13e30 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65  */.  void (*xFre
13e40 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
13e50 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72      /* Free a pr
13e60 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a  ior allocation *
13e70 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61  /.  void *(*xRea
13e80 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29  lloc)(void*,int)
13e90 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20  ;  /* Resize an 
13ea0 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
13eb0 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69  int (*xSize)(voi
13ec0 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
13ed0 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a  * Return the siz
13ee0 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69  e of an allocati
13ef0 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52  on */.  int (*xR
13f00 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20  oundup)(int);   
13f10 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20         /* Round 
13f20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20  up request size 
13f30 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  to allocation si
13f40 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49  ze */.  int (*xI
13f50 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  nit)(void*);    
13f60 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61         /* Initia
13f70 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
13f80 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
13f90 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29  oid (*xShutdown)
13fa0 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a  (void*);      /*
13fb0 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68   Deinitialize th
13fc0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
13fd0 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41  or */.  void *pA
13fe0 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20  ppData;         
13ff0 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65         /* Argume
14000 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e  nt to xInit() an
14010 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f  d xShutdown() */
14020 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
14030 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69  REF: Configurati
14040 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45  on Options.** KE
14050 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75  YWORDS: {configu
14060 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a  ration option}.*
14070 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
14080 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
14090 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
140a0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
140b0 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
140c0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
140d0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
140e0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
140f0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
14100 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
14110 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
14120 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
14130 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
14140 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
14150 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
14160 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
14170 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
14180 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
14190 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
141a0 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
141b0 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
141c0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
141d0 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
141e0 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
141f0 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69  rked.  The [sqli
14200 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
14210 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
14220 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
14230 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
14240 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
14250 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
14260 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
14270 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
14280 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
14290 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
142a0 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d  G_SINGLETHREAD]]
142b0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
142c0 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c  IG_SINGLETHREAD<
142d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
142e0 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
142f0 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
14300 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
14310 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
14320 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
14330 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20   Single-thread. 
14340 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
14350 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20   it disables.** 
14360 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64  all mutexing and
14370 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74   puts SQLite int
14380 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69  o a mode where i
14390 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73  t can only be us
143a0 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c  ed.** by a singl
143b0 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20  e thread.   ^If 
143c0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
143d0 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
143e0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
143f0 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
14400 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
14410 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
14420 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
14430 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67  ossible to chang
14440 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67  e the [threading
14450 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20   mode] from its 
14460 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65  default.** value
14470 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   of Single-threa
14480 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65  d and so [sqlite
14490 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
144a0 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c   return .** [SQL
144b0 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
144c0 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51  lled with the SQ
144d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
144e0 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66  LETHREAD.** conf
144f0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
14500 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
14510 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
14520 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53  TITHREAD]] <dt>S
14530 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
14540 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  TITHREAD</dt>.**
14550 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
14560 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
14570 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
14580 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
14590 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
145a0 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d   mode] to Multi-
145b0 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
145c0 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
145d0 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67  bles.** mutexing
145e0 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
145f0 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
14600 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
14610 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54  t] objects..** T
14620 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
14630 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
14640 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63  r serializing ac
14650 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61  cess to.** [data
14660 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
14670 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
14680 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75  statements].  Bu
14690 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a  t other mutexes.
146a0 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73  ** are enabled s
146b0 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  o that SQLite wi
146c0 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73  ll be safe to us
146d0 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  e in a multi-thr
146e0 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e  eaded.** environ
146f0 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20  ment as long as 
14700 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61  no two threads a
14710 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
14720 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62  e same.** [datab
14730 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
14740 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
14750 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  .  ^If SQLite is
14760 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
14770 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
14780 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
14790 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
147a0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
147b0 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
147c0 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
147d0 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d  o set the Multi-
147e0 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
147f0 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
14800 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
14810 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
14820 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
14830 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
14840 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
14850 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e  _MULTITHREAD con
14860 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
14870 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
14880 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
14890 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53  RIALIZED]] <dt>S
148a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
148b0 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20  IALIZED</dt>.** 
148c0 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
148d0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
148e0 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
148f0 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
14900 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
14910 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69  mode] to Seriali
14920 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f  zed. In other wo
14930 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e  rds, this option
14940 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20   enables.** all 
14950 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e  mutexes includin
14960 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a  g the recursive.
14970 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64  ** mutexes on [d
14980 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14990 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
149a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
149b0 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73  ects..** In this
149c0 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20   mode (which is 
149d0 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e  the default when
149e0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
149f0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c  led with.** [SQL
14a00 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
14a10 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  ]) the SQLite li
14a20 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c  brary will itsel
14a30 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65  f serialize acce
14a40 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61  ss.** to [databa
14a50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
14a60 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
14a70 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61  atements] so tha
14a80 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61  t the.** applica
14a90 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20  tion is free to 
14aa0 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61  use the same [da
14ab0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14ac0 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d  n] or the.** sam
14ad0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
14ae0 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72  ement] in differ
14af0 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74  ent threads at t
14b00 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a  he same time..**
14b10 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
14b20 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
14b30 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
14b40 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
14b50 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
14b60 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
14b70 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
14b80 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
14b90 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a  set the Serializ
14ba0 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
14bb0 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
14bc0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
14bd0 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
14be0 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
14bf0 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
14c00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
14c10 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72  IALIZED configur
14c20 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
14c30 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
14c40 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
14c50 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14c60 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  FIG_MALLOC</dt>.
14c70 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
14c80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
14c90 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  OC option takes 
14ca0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
14cb0 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61  t which is .** a
14cc0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
14cd0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
14ce0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
14cf0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a  ods] structure..
14d00 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  ** The argument 
14d10 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74  specifies.** alt
14d20 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76  ernative low-lev
14d30 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  el memory alloca
14d40 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f  tion routines to
14d50 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63   be used in plac
14d60 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f  e of.** the memo
14d70 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
14d80 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
14d90 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c  o SQLite.)^ ^SQL
14da0 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73  ite makes.** its
14db0 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
14dc0 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74  y of the content
14dd0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
14de0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
14df0 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72  ructure.** befor
14e00 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  e the [sqlite3_c
14e10 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65  onfig()] call re
14e20 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  turns.</dd>.**.*
14e30 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14e40 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64  G_GETMALLOC]] <d
14e50 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14e60 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  GETMALLOC</dt>.*
14e70 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
14e80 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
14e90 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65  LLOC option take
14ea0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
14eb0 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ent which.** is 
14ec0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
14ed0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
14ee0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
14ef0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
14f00 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
14f10 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  _mem_methods].**
14f20 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
14f30 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
14f40 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
14f50 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
14f60 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  n routines.)^.**
14f70 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
14f80 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
14f90 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
14fa0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
14fb0 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
14fc0 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68  ith a wrapper th
14fd0 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d  at simulations m
14fe0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14ff0 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74   failure or.** t
15000 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61  racks memory usa
15010 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ge, for example.
15020 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
15030 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
15040 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c  STATUS]] <dt>SQL
15050 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
15060 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATUS</dt>.** <dd
15070 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
15080 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f  NFIG_MEMSTATUS o
15090 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67  ption takes sing
150a0 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  le argument of t
150b0 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65  ype int,.** inte
150c0 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f  rpreted as a boo
150d0 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62  lean, which enab
150e0 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
150f0 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f  the collection o
15100 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  f.** memory allo
15110 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
15120 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79  s. ^(When memory
15130 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
15140 69 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 69  istics are.** di
15150 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c  sabled, the foll
15160 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74  owing SQLite int
15170 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e  erfaces become n
15180 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a  on-operational:.
15190 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  **   <ul>.**   <
151a0 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
151b0 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20  ory_used()].**  
151c0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
151d0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
151e0 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
151f0 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
15200 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20  limit64()].**   
15210 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74  <li> [sqlite3_st
15220 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c  atus64()].**   <
15230 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72  /ul>)^.** ^Memor
15240 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
15250 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62  tistics are enab
15260 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75  led by default u
15270 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a  nless SQLite is.
15280 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
15290 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54   [SQLITE_DEFAULT
152a0 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e  _MEMSTATUS]=0 in
152b0 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f   which case memo
152c0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
152d0 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
152e0 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
152f0 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ult..** </dd>.**
15300 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15310 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64  FIG_SCRATCH]] <d
15320 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
15330 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20  SCRATCH</dt>.** 
15340 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45  <dd> ^The SQLITE
15350 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20  _CONFIG_SCRATCH 
15360 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
15370 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
15380 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
15390 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66  SQLite can use f
153a0 6f 72 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  or scratch memor
153b0 79 2e 20 20 5e 28 54 68 65 72 65 20 61 72 65 20  y.  ^(There are 
153c0 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 0a  three arguments.
153d0 2a 2a 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e  ** to SQLITE_CON
153e0 46 49 47 5f 53 43 52 41 54 43 48 3a 20 20 41 20  FIG_SCRATCH:  A 
153f0 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74  pointer an 8-byt
15400 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d  e.** aligned mem
15410 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20  ory buffer from 
15420 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63  which the scratc
15430 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69  h allocations wi
15440 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20  ll be.** drawn, 
15450 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
15460 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
15470 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64  ion (sz),.** and
15480 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
15490 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61  ber of scratch a
154a0 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 29  llocations (N).)
154b0 5e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ^.** The first a
154c0 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
154d0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
154e0 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62  8-byte aligned b
154f0 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c  uffer.** of at l
15500 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20  east sz*N bytes 
15510 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53  of memory..** ^S
15520 51 4c 69 74 65 20 77 69 6c 6c 20 6e 6f 74 20 75  QLite will not u
15530 73 65 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  se more than one
15540 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73   scratch buffers
15550 20 70 65 72 20 74 68 72 65 61 64 2e 0a 2a 2a 20   per thread..** 
15560 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76  ^SQLite will nev
15570 65 72 20 72 65 71 75 65 73 74 20 61 20 73 63 72  er request a scr
15580 61 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74  atch buffer that
15590 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a   is more than 6.
155a0 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 74  ** times the dat
155b0 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e  abase page size.
155c0 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 6e  .** ^If SQLite n
155d0 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 74  eeds needs addit
155e0 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68  ional.** scratch
155f0 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77   memory beyond w
15600 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
15610 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72  by this configur
15620 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68  ation option, th
15630 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  en .** [sqlite3_
15640 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62  malloc()] will b
15650 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
15660 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64   the memory need
15670 65 64 2e 3c 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20  ed.<p>.** ^When 
15680 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
15690 70 72 6f 76 69 64 65 73 20 61 6e 79 20 61 6d 6f  provides any amo
156a0 75 6e 74 20 6f 66 20 73 63 72 61 74 63 68 20 6d  unt of scratch m
156b0 65 6d 6f 72 79 20 75 73 69 6e 67 0a 2a 2a 20 53  emory using.** S
156c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
156d0 41 54 43 48 2c 20 53 51 4c 69 74 65 20 61 76 6f  ATCH, SQLite avo
156e0 69 64 73 20 75 6e 6e 65 63 65 73 73 61 72 79 20  ids unnecessary 
156f0 6c 61 72 67 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  large.** [sqlite
15700 33 5f 6d 61 6c 6c 6f 63 7c 68 65 61 70 20 61 6c  3_malloc|heap al
15710 6c 6f 63 61 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54  locations]..** T
15720 68 69 73 20 63 61 6e 20 68 65 6c 70 20 5b 52 6f  his can help [Ro
15730 62 73 6f 6e 20 70 72 6f 6f 66 7c 70 72 65 76 65  bson proof|preve
15740 6e 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  nt memory alloca
15750 74 69 6f 6e 20 66 61 69 6c 75 72 65 73 5d 20 64  tion failures] d
15760 75 65 20 74 6f 20 68 65 61 70 0a 2a 2a 20 66 72  ue to heap.** fr
15770 61 67 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 20 6c  agmentation in l
15780 6f 77 2d 6d 65 6d 6f 72 79 20 65 6d 62 65 64 64  ow-memory embedd
15790 65 64 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c  ed systems..** <
157a0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
157b0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
157c0 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ACHE]] <dt>SQLIT
157d0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
157e0 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  HE</dt>.** <dd> 
157f0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
15800 49 47 5f 50 41 47 45 43 41 43 48 45 20 6f 70 74  IG_PAGECACHE opt
15810 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
15820 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74  memory pool.** t
15830 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
15840 73 65 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  se for the datab
15850 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77  ase page cache w
15860 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20  ith the default 
15870 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d  page.** cache im
15880 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a  plementation.  .
15890 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72  ** This configur
158a0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
158b0 61 20 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61 70  a no-op if an ap
158c0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
158d0 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69   page.** cache i
158e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
158f0 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68   loaded using th
15900 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
15910 5f 50 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54  _PCACHE2]..** ^T
15920 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
15930 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49  rguments to SQLI
15940 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
15950 43 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74  CHE: A pointer t
15960 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67  o.** 8-byte alig
15970 6e 65 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65 6d  ned memory (pMem
15980 29 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  ), the size of e
15990 61 63 68 20 70 61 67 65 20 63 61 63 68 65 20 6c  ach page cache l
159a0 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64  ine (sz),.** and
159b0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
159c0 61 63 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e 0a  ache lines (N)..
159d0 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65  ** The sz argume
159e0 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65  nt should be the
159f0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72   size of the lar
15a00 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61  gest database pa
15a10 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f  ge.** (a power o
15a20 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31  f two between 51
15a30 32 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75  2 and 65536) plu
15a40 73 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74  s some extra byt
15a50 65 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70  es for each.** p
15a60 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68  age header.  ^Th
15a70 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72  e number of extr
15a80 61 20 62 79 74 65 73 20 6e 65 65 64 65 64 20 62  a bytes needed b
15a90 79 20 74 68 65 20 70 61 67 65 20 68 65 61 64 65  y the page heade
15aa0 72 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65  r.** can be dete
15ab0 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 5b 53 51  rmined using [SQ
15ac0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
15ad0 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49  HE_HDRSZ]..** ^I
15ae0 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61  t is harmless, a
15af0 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61  part from the wa
15b00 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20  sted memory,.** 
15b10 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61 6d  for the sz param
15b20 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67 65  eter to be large
15b30 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72 79  r than necessary
15b40 2e 20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 61  .  The pMem.** a
15b50 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
15b60 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f  either a NULL po
15b70 69 6e 74 65 72 20 6f 72 20 61 20 70 6f 69 6e 74  inter or a point
15b80 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a  er to an 8-byte.
15b90 2a 2a 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b  ** aligned block
15ba0 20 6f 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74   of memory of at
15bb0 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65   least sz*N byte
15bc0 73 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20  s, otherwise.** 
15bd0 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
15be0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
15bf0 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d 20  ..** ^When pMem 
15c00 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c  is not NULL, SQL
15c10 69 74 65 20 77 69 6c 6c 20 73 74 72 69 76 65 20  ite will strive 
15c20 74 6f 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72  to use the memor
15c30 79 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74 6f  y provided.** to
15c40 20 73 61 74 69 73 66 79 20 70 61 67 65 20 63 61   satisfy page ca
15c50 63 68 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c 69  che needs, falli
15c60 6e 67 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c 69  ng back to [sqli
15c70 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 66  te3_malloc()] if
15c80 0a 2a 2a 20 61 20 70 61 67 65 20 63 61 63 68 65  .** a page cache
15c90 20 6c 69 6e 65 20 69 73 20 6c 61 72 67 65 72 20   line is larger 
15ca0 74 68 61 6e 20 73 7a 20 62 79 74 65 73 20 6f 72  than sz bytes or
15cb0 20 69 66 20 61 6c 6c 20 6f 66 20 74 68 65 20 70   if all of the p
15cc0 4d 65 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  Mem buffer.** is
15cd0 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e   exhausted..** ^
15ce0 49 66 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c 20  If pMem is NULL 
15cf0 61 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72  and N is non-zer
15d00 6f 2c 20 74 68 65 6e 20 65 61 63 68 20 64 61 74  o, then each dat
15d10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15d20 0a 2a 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69 74  .** does an init
15d30 69 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 74  ial bulk allocat
15d40 69 6f 6e 20 66 6f 72 20 70 61 67 65 20 63 61 63  ion for page cac
15d50 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f  he memory.** fro
15d60 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
15d70 63 28 29 5d 20 73 75 66 66 69 63 69 65 6e 74 20  c()] sufficient 
15d80 66 6f 72 20 4e 20 63 61 63 68 65 20 6c 69 6e 65  for N cache line
15d90 73 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69  s if N is positi
15da0 76 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 32  ve or.** of -102
15db0 34 2a 4e 20 62 79 74 65 73 20 69 66 20 4e 20 69  4*N bytes if N i
15dc0 73 20 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e 49  s negative, . ^I
15dd0 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  f additional.** 
15de0 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
15df0 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f  y is needed beyo
15e00 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
15e10 64 65 64 20 62 79 20 74 68 65 20 69 6e 69 74 69  ded by the initi
15e20 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  al.** allocation
15e30 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 67 6f  , then SQLite go
15e40 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d  es to [sqlite3_m
15e50 61 6c 6c 6f 63 28 29 5d 20 73 65 70 61 72 61 74  alloc()] separat
15e60 65 6c 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  ely for each.** 
15e70 61 64 64 69 74 69 6f 6e 61 6c 20 63 61 63 68 65  additional cache
15e80 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   line. </dd>.**.
15e90 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
15ea0 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51  IG_HEAP]] <dt>SQ
15eb0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
15ec0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
15ed0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
15ee0 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65  _HEAP option spe
15ef0 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
15f00 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a  memory buffer .*
15f10 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  * that SQLite wi
15f20 6c 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f  ll use for all o
15f30 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65  f its dynamic me
15f40 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
15f50 6e 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20  needs.** beyond 
15f60 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66  those provided f
15f70 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f  or by [SQLITE_CO
15f80 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e  NFIG_SCRATCH] an
15f90 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  d.** [SQLITE_CON
15fa0 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a  FIG_PAGECACHE]..
15fb0 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  ** ^The SQLITE_C
15fc0 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f  ONFIG_HEAP optio
15fd0 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  n is only availa
15fe0 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73  ble if SQLite is
15ff0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74   compiled.** wit
16000 68 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  h either [SQLITE
16010 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d  _ENABLE_MEMSYS3]
16020 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42   or [SQLITE_ENAB
16030 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20  LE_MEMSYS5] and 
16040 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49  returns.** [SQLI
16050 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76  TE_ERROR] if inv
16060 6f 6b 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a  oked otherwise..
16070 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68  ** ^There are th
16080 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ree arguments to
16090 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
160a0 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74  EAP:.** An 8-byt
160b0 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65  e aligned pointe
160c0 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c  r to the memory,
160d0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
160e0 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d  f bytes in the m
160f0 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e  emory buffer, an
16100 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  d the minimum al
16110 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a  location size..*
16120 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20  * ^If the first 
16130 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
16140 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20  ory pointer) is 
16150 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74  NULL, then SQLit
16160 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20  e reverts.** to 
16170 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c  using its defaul
16180 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
16190 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d  or (the system m
161a0 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e  alloc() implemen
161b0 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f  tation),.** undo
161c0 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e  ing any prior in
161d0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c  vocation of [SQL
161e0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
161f0 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  C].  ^If the.** 
16200 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69  memory pointer i
16210 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
16220 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20  the alternative 
16230 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
16240 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74  tor is engaged t
16250 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20  o handle all of 
16260 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61  SQLites memory a
16270 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
16280 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f  .** The first po
16290 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
162a0 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20  y pointer) must 
162b0 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
162c0 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64   8-byte.** bound
162d0 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e  ary or subsequen
162e0 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  t behavior of SQ
162f0 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64  Lite will be und
16300 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d  efined..** The m
16310 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
16320 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64  n size is capped
16330 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f   at 2**12. Reaso
16340 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20  nable values.** 
16350 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  for the minimum 
16360 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
16370 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68  are 2**5 through
16380 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a   2**8.</dd>.**.*
16390 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
163a0 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51  G_MUTEX]] <dt>SQ
163b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
163c0 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
163d0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
163e0 49 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20  IG_MUTEX option 
163f0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
16400 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
16410 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f   a.** pointer to
16420 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
16430 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
16440 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
16450 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72  cture..** The ar
16460 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
16470 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
16480 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75  -level mutex rou
16490 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64  tines to be used
164a0 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65  .** in place the
164b0 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
164c0 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
164d0 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61  e.)^  ^SQLite ma
164e0 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  kes a copy of.**
164f0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
16500 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
16510 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
16520 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65  cture before the
16530 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
16540 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72  ite3_config()] r
16550 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69  eturns. ^If SQLi
16560 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
16570 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
16580 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
16590 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
165a0 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
165b0 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
165c0 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65   the entire mute
165d0 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69  xing subsystem i
165e0 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
165f0 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e  he build and hen
16600 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ce calls to.** [
16610 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
16620 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  ] with the SQLIT
16630 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63  E_CONFIG_MUTEX c
16640 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
16650 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75  ion will.** retu
16660 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
16670 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ].</dd>.**.** [[
16680 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
16690 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c  TMUTEX]] <dt>SQL
166a0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
166b0 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
166c0 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
166d0 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70  NFIG_GETMUTEX op
166e0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
166f0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
16700 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
16710 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
16720 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
16730 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
16740 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
16750 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  .** [sqlite3_mut
16760 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  ex_methods].** s
16770 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
16780 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
16790 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75  ently defined mu
167a0 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a  tex routines.)^.
167b0 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63  ** This option c
167c0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76  an be used to ov
167d0 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75  erload the defau
167e0 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74  lt mutex allocat
167f0 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
16800 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75  with a wrapper u
16810 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74  sed to track mut
16820 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72  ex usage for per
16830 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66  formance.** prof
16840 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67  iling or testing
16850 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20  , for example.  
16860 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
16870 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
16880 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
16890 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
168a0 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
168b0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
168c0 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e  n then.** the en
168d0 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75  tire mutexing su
168e0 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74  bsystem is omitt
168f0 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c  ed from the buil
16900 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c  d and hence call
16910 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
16920 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20  _config()] with 
16930 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
16940 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69  G_GETMUTEX confi
16950 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
16960 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  will.** return [
16970 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f  SQLITE_ERROR].</
16980 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
16990 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
169a0 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  IDE]] <dt>SQLITE
169b0 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
169c0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
169d0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
169e0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74  IG_LOOKASIDE opt
169f0 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72  ion takes two ar
16a00 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74  guments that det
16a10 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65  ermine.** the de
16a20 66 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f  fault size of lo
16a30 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f  okaside memory o
16a40 6e 20 65 61 63 68 20 5b 64 61 74 61 62 61 73 65  n each [database
16a50 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
16a60 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
16a70 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
16a80 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
16a90 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
16aa0 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
16ab0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
16ac0 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61  .** slots alloca
16ad0 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61  ted to each data
16ae0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
16af0 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e  )^  ^(SQLITE_CON
16b00 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a  FIG_LOOKASIDE.**
16b10 20 73 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66   sets the <i>def
16b20 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69  ault</i> lookasi
16b30 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51  de size. The [SQ
16b40 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
16b50 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69  OKASIDE].** opti
16b60 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  on to [sqlite3_d
16b70 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20  b_config()] can 
16b80 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67  be used to chang
16b90 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a  e the lookaside.
16ba0 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
16bb0 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63   on individual c
16bc0 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f  onnections.)^ </
16bd0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
16be0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
16bf0 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  2]] <dt>SQLITE_C
16c00 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64  ONFIG_PCACHE2</d
16c10 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
16c20 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
16c30 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61  CACHE2 option ta
16c40 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
16c50 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a  ument which is .
16c60 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
16c70 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  an [sqlite3_pcac
16c80 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
16c90 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  ect.  This objec
16ca0 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74  t specifies.** t
16cb0 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  he interface to 
16cc0 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61  a custom page ca
16cd0 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
16ce0 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65  on.)^.** ^SQLite
16cf0 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
16d00 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63   the [sqlite3_pc
16d10 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
16d20 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  bject.</dd>.**.*
16d30 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
16d40 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c  G_GETPCACHE2]] <
16d50 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
16d60 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e  _GETPCACHE2</dt>
16d70 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
16d80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
16d90 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74  PCACHE2 option t
16da0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
16db0 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20  gument which.** 
16dc0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
16dd0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  an [sqlite3_pcac
16de0 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
16df0 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70  ect.  SQLite cop
16e00 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75  ies of.** the cu
16e10 72 72 65 6e 74 20 70 61 67 65 20 63 61 63 68 65  rrent page cache
16e20 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
16e30 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74  into that object
16e40 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
16e50 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
16e60 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOG]] <dt>SQLITE
16e70 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e  _CONFIG_LOG</dt>
16e80 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c  .** <dd> The SQL
16e90 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f  ITE_CONFIG_LOG o
16ea0 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
16eb0 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53   configure the S
16ec0 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20  QLite.** global 
16ed0 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20  [error log]..** 
16ee0 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  (^The SQLITE_CON
16ef0 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74  FIG_LOG option t
16f00 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e  akes two argumen
16f10 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ts: a pointer to
16f20 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77   a.** function w
16f30 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61  ith a call signa
16f40 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28  ture of void(*)(
16f50 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
16f60 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20  char*), .** and 
16f70 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69  a pointer to voi
16f80 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74  d. ^If the funct
16f90 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ion pointer is n
16fa0 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a  ot NULL, it is.*
16fb0 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71  * invoked by [sq
16fc0 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20  lite3_log()] to 
16fd0 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67  process each log
16fe0 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  ging event.  ^If
16ff0 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
17000 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c   pointer is NULL
17010 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  , the [sqlite3_l
17020 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  og()] interface 
17030 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e  becomes a no-op.
17040 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f  .** ^The void po
17050 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68  inter that is th
17060 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
17070 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  t to SQLITE_CONF
17080 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73  IG_LOG is.** pas
17090 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74  sed through as t
170a0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
170b0 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  er to the applic
170c0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f  ation-defined lo
170d0 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gger.** function
170e0 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66   whenever that f
170f0 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b  unction is invok
17100 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64  ed.  ^The second
17110 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
17120 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
17130 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f  tion is a copy o
17140 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  f the first para
17150 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72  meter to the cor
17160 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73  responding.** [s
17170 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61  qlite3_log()] ca
17180 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64  ll and is intend
17190 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75  ed to be a [resu
171a0 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a  lt code] or an.*
171b0 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
171c0 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20  lt code].  ^The 
171d0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
171e0 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f  passed to the lo
171f0 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d  gger is.** log m
17200 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72  essage after for
17210 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c  matting via [sql
17220 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
17230 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
17240 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63  logging interfac
17250 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61  e is not reentra
17260 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66  nt; the logger f
17270 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c  unction.** suppl
17280 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69  ied by the appli
17290 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
172a0 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74  invoke any SQLit
172b0 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20  e interface..** 
172c0 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61  In a multi-threa
172d0 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c  ded application,
172e0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
172f0 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a  -defined logger.
17300 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
17310 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20   be threadsafe. 
17320 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
17330 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d  LITE_CONFIG_URI]
17340 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
17350 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e  FIG_URI.** <dd>^
17360 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
17370 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61  IG_URI option ta
17380 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
17390 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
173a0 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72  t..** If non-zer
173b0 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64  o, then URI hand
173c0 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
173d0 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65   enabled. If the
173e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65   parameter is ze
173f0 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20  ro,.** then URI 
17400 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
17410 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e  ally disabled.)^
17420 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e   ^If URI handlin
17430 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a  g is globally.**
17440 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69   enabled, all fi
17450 6c 65 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74  lenames passed t
17460 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
17470 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
17480 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  n_v2()],.** [sql
17490 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f  ite3_open16()] o
174a0 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61  r.** specified a
174b0 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43  s part of [ATTAC
174c0 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20  H] commands are 
174d0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
174e0 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a  RIs, regardless.
174f0 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ** of whether or
17500 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45   not the [SQLITE
17510 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
17520 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20  is set when the 
17530 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
17540 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64  ection is opened
17550 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62  . ^If it is glob
17560 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66  ally disabled, f
17570 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20  ilenames are.** 
17580 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64  only interpreted
17590 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20   as URIs if the 
175a0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20  SQLITE_OPEN_URI 
175b0 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e  flag is set when
175c0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
175d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
175e0 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61  pened. ^(By defa
175f0 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e  ult, URI handlin
17600 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a  g is globally.**
17610 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64   disabled. The d
17620 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79  efault value may
17630 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63   be changed by c
17640 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68  ompiling with th
17650 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45  e.** [SQLITE_USE
17660 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66  _URI] symbol def
17670 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  ined.)^.**.** [[
17680 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
17690 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
176a0 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  N]] <dt>SQLITE_C
176b0 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
176c0 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64  NDEX_SCAN.** <dd
176d0 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
176e0 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
176f0 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74  EX_SCAN option t
17700 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e  akes a single in
17710 74 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e  teger.** argumen
17720 74 20 77 68 69 63 68 20 69 73 20 69 6e 74 65 72  t which is inter
17730 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c  preted as a bool
17740 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ean in order to 
17750 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
17760 65 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20  e.** the use of 
17770 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73  covering indices
17780 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20   for full table 
17790 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65  scans in the que
177a0 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a  ry optimizer..**
177b0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65   ^The default se
177c0 74 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69  tting is determi
177d0 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53  ned.** by the [S
177e0 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45  QLITE_ALLOW_COVE
177f0 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d  RING_INDEX_SCAN]
17800 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
17810 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22  tion, or is "on"
17820 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70  .** if that comp
17830 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
17840 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54  is omitted..** T
17850 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69  he ability to di
17860 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66  sable the use of
17870 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65   covering indice
17880 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65  s for full table
17890 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63   scans.** is bec
178a0 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72  ause some incorr
178b0 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61  ectly coded lega
178c0 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  cy applications 
178d0 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f  might malfunctio
178e0 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70  n.** when the op
178f0 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e  timization is en
17900 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e  abled.  Providin
17910 67 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f  g the ability to
17920 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20  .** disable the 
17930 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c  optimization all
17940 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62  ows the older, b
17950 75 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e  uggy application
17960 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a   code to work.**
17970 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20   without change 
17980 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20  even with newer 
17990 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
179a0 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  te..**.** [[SQLI
179b0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
179c0 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ]] [[SQLITE_CONF
179d0 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a  IG_GETPCACHE]].*
179e0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
179f0 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53  FIG_PCACHE and S
17a00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
17a10 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54  PCACHE.** <dd> T
17a20 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65  hese options are
17a30 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68   obsolete and sh
17a40 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64  ould not be used
17a50 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a   by new code..**
17a60 20 54 68 65 79 20 61 72 65 20 72 65 74 61 69 6e   They are retain
17a70 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
17a80 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62   compatibility b
17a90 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70  ut are now no-op
17aa0 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  s..** </dd>.**.*
17ab0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
17ac0 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64  G_SQLLOG]].** <d
17ad0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
17ae0 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68  SQLLOG.** <dd>Th
17af0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c  is option is onl
17b00 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73  y available if s
17b10 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  qlite is compile
17b20 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  d with the.** [S
17b30 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c  QLITE_ENABLE_SQL
17b40 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73  LOG] pre-process
17b50 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64  or macro defined
17b60 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  . The first argu
17b70 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62  ment should.** b
17b80 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
17b90 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70   function of typ
17ba0 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  e void(*)(void*,
17bb0 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63  sqlite3*,const c
17bc0 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54  har*, int)..** T
17bd0 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64  he second should
17be0 20 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69   be of type (voi
17bf0 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63  d*). The callbac
17c00 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20  k is invoked by 
17c10 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69  the library.** i
17c20 6e 20 74 68 72 65 65 20 73 65 70 61 72 61 74 65  n three separate
17c30 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20   circumstances, 
17c40 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
17c50 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  e value passed a
17c60 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  s the.** fourth 
17c70 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68  parameter. If th
17c80 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
17c90 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68  er is 0, then th
17ca0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
17cb0 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20  ction.** passed 
17cc0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
17cd0 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20  gument has just 
17ce0 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65  been opened. The
17cf0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a   third argument.
17d00 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62  ** points to a b
17d10 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67  uffer containing
17d20 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
17d30 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66   main database f
17d40 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66  ile. If the.** f
17d50 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
17d60 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53  is 1, then the S
17d70 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  QL statement tha
17d80 74 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  t the third para
17d90 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20  meter.** points 
17da0 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e  to has just been
17db0 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69   executed. Or, i
17dc0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
17dd0 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68 65  ameter is 2, the
17de0 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74  n.** the connect
17df0 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64  ion being passed
17e00 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
17e10 61 72 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e  arameter is bein
17e20 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a  g closed. The.**
17e30 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
17e40 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20   is passed NULL 
17e50 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20 41  In this case.  A
17e60 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69  n example of usi
17e70 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69  ng this.** confi
17e80 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
17e90 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74  can be seen in t
17ea0 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e  he "test_sqllog.
17eb0 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69  c" source file i
17ec0 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63  n.** the canonic
17ed0 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65  al SQLite source
17ee0 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a   tree.</dd>.**.*
17ef0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
17f00 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a  G_MMAP_SIZE]].**
17f10 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
17f20 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20  IG_MMAP_SIZE.** 
17f30 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46  <dd>^SQLITE_CONF
17f40 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b  IG_MMAP_SIZE tak
17f50 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e  es two 64-bit in
17f60 74 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69  teger (sqlite3_i
17f70 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20  nt64) values.** 
17f80 74 68 61 74 20 61 72 65 20 74 68 65 20 64 65 66  that are the def
17f90 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c  ault mmap size l
17fa0 69 6d 69 74 20 28 74 68 65 20 64 65 66 61 75 6c  imit (the defaul
17fb0 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a  t setting for.**
17fc0 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69   [PRAGMA mmap_si
17fd0 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78  ze]) and the max
17fe0 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61  imum allowed mma
17ff0 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a  p size limit..**
18000 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65   ^The default se
18010 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65  tting can be ove
18020 72 72 69 64 64 65 6e 20 62 79 20 65 61 63 68 20  rridden by each 
18030 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18040 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74  ion using.** eit
18050 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20  her the [PRAGMA 
18060 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61  mmap_size] comma
18070 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20  nd, or by using 
18080 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  the.** [SQLITE_F
18090 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  CNTL_MMAP_SIZE] 
180a0 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e  file control.  ^
180b0 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c  (The maximum all
180c0 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a  owed mmap size.*
180d0 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74  * will be silent
180e0 6c 79 20 74 72 75 6e 63 61 74 65 64 20 69 66 20  ly truncated if 
180f0 6e 65 63 65 73 73 61 72 79 20 73 6f 20 74 68 61  necessary so tha
18100 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78  t it does not ex
18110 63 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ceed the.** comp
18120 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d  ile-time maximum
18130 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62   mmap size set b
18140 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  y the.** [SQLITE
18150 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  _MAX_MMAP_SIZE] 
18160 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
18170 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69  ion.)^.** ^If ei
18180 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f  ther argument to
18190 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20   this option is 
181a0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
181b0 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  hat argument is.
181c0 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74  ** changed to it
181d0 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64  s compile-time d
181e0 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  efault..**.** [[
181f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
18200 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a  N32_HEAPSIZE]].*
18210 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
18220 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
18230 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  ZE.** <dd>^The S
18240 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
18250 33 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69  32_HEAPSIZE opti
18260 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  on is only avail
18270 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69  able if SQLite i
18280 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f  s.** compiled fo
18290 72 20 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74  r Windows with t
182a0 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32  he [SQLITE_WIN32
182b0 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f  _MALLOC] pre-pro
182c0 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20  cessor macro.** 
182d0 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45  defined. ^SQLITE
182e0 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
182f0 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33  APSIZE takes a 3
18300 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69  2-bit unsigned i
18310 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20  nteger value.** 
18320 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74  that specifies t
18330 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
18340 6f 66 20 74 68 65 20 63 72 65 61 74 65 64 20 68  of the created h
18350 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  eap..**.** [[SQL
18360 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
18370 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74  E_HDRSZ]].** <dt
18380 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
18390 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c  CACHE_HDRSZ.** <
183a0 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
183b0 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
183c0 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  SZ option takes 
183d0 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74  a single paramet
183e0 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  er which.** is a
183f0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
18400 6e 74 65 67 65 72 20 61 6e 64 20 77 72 69 74 65  nteger and write
18410 73 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65  s into that inte
18420 67 65 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ger the number o
18430 66 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73  f extra.** bytes
18440 20 70 65 72 20 70 61 67 65 20 72 65 71 75 69 72   per page requir
18450 65 64 20 66 6f 72 20 65 61 63 68 20 70 61 67 65  ed for each page
18460 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   in [SQLITE_CONF
18470 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
18480 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  * The amount of 
18490 65 78 74 72 61 20 73 70 61 63 65 20 72 65 71 75  extra space requ
184a0 69 72 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20  ired can change 
184b0 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
184c0 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61   compiler,.** ta
184d0 72 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61  rget platform, a
184e0 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
184f0 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  n..**.** [[SQLIT
18500 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d  E_CONFIG_PMASZ]]
18510 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
18520 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c  ONFIG_PMASZ.** <
18530 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
18540 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69  ONFIG_PMASZ opti
18550 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
18560 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63  e parameter whic
18570 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 67  h.** is an unsig
18580 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20  ned integer and 
18590 73 65 74 73 20 74 68 65 20 22 4d 69 6e 69 6d 75  sets the "Minimu
185a0 6d 20 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 20  m PMA Size" for 
185b0 74 68 65 20 6d 75 6c 74 69 74 68 72 65 61 64 65  the multithreade
185c0 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 74  d.** sorter to t
185d0 68 61 74 20 69 6e 74 65 67 65 72 2e 20 20 54 68  hat integer.  Th
185e0 65 20 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75  e default minimu
185f0 6d 20 50 4d 41 20 53 69 7a 65 20 69 73 20 73 65  m PMA Size is se
18600 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  t by the.** [SQL
18610 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a  ITE_SORTER_PMASZ
18620 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
18630 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65  ption.  New thre
18640 61 64 73 20 61 72 65 20 6c 61 75 6e 63 68 65 64  ads are launched
18650 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 68  .** to help with
18660 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73   sort operations
18670 20 77 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 61   when multithrea
18680 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69  ded sorting.** i
18690 73 20 65 6e 61 62 6c 65 64 20 28 75 73 69 6e 67  s enabled (using
186a0 20 74 68 65 20 5b 50 52 41 47 4d 41 20 74 68 72   the [PRAGMA thr
186b0 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61  eads] command) a
186c0 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66  nd the amount of
186d0 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62   content.** to b
186e0 65 20 73 6f 72 74 65 64 20 65 78 63 65 65 64 73  e sorted exceeds
186f0 20 74 68 65 20 70 61 67 65 20 73 69 7a 65 20 74   the page size t
18700 69 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d  imes the minimum
18710 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47   of the.** [PRAG
18720 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 73  MA cache_size] s
18730 65 74 74 69 6e 67 20 61 6e 64 20 74 68 69 73 20  etting and this 
18740 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  value..**.** [[S
18750 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d  QLITE_CONFIG_STM
18760 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a 2a  TJRNL_SPILL]].**
18770 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
18780 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c  IG_STMTJRNL_SPIL
18790 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  L.** <dd>^The SQ
187a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54  LITE_CONFIG_STMT
187b0 4a 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74 69 6f  JRNL_SPILL optio
187c0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
187d0 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68   parameter which
187e0 0a 2a 2a 20 62 65 63 6f 6d 65 73 20 74 68 65 20  .** becomes the 
187f0 5b 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e  [statement journ
18800 61 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64 69 73  al] spill-to-dis
18810 6b 20 74 68 72 65 73 68 6f 6c 64 2e 20 20 0a 2a  k threshold.  .*
18820 2a 20 5b 53 74 61 74 65 6d 65 6e 74 20 6a 6f 75  * [Statement jou
18830 72 6e 61 6c 73 5d 20 61 72 65 20 68 65 6c 64 20  rnals] are held 
18840 69 6e 20 6d 65 6d 6f 72 79 20 75 6e 74 69 6c 20  in memory until 
18850 74 68 65 69 72 20 73 69 7a 65 20 28 69 6e 20 62  their size (in b
18860 79 74 65 73 29 0a 2a 2a 20 65 78 63 65 65 64 73  ytes).** exceeds
18870 20 74 68 69 73 20 74 68 72 65 73 68 6f 6c 64 2c   this threshold,
18880 20 61 74 20 77 68 69 63 68 20 70 6f 69 6e 74 20   at which point 
18890 74 68 65 79 20 61 72 65 20 77 72 69 74 74 65 6e  they are written
188a0 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72 20   to disk..** Or 
188b0 69 66 20 74 68 65 20 74 68 72 65 73 68 6f 6c 64  if the threshold
188c0 20 69 73 20 2d 31 2c 20 73 74 61 74 65 6d 65 6e   is -1, statemen
188d0 74 20 6a 6f 75 72 6e 61 6c 73 20 61 72 65 20 61  t journals are a
188e0 6c 77 61 79 73 20 68 65 6c 64 0a 2a 2a 20 65 78  lways held.** ex
188f0 63 6c 75 73 69 76 65 6c 79 20 69 6e 20 6d 65 6d  clusively in mem
18900 6f 72 79 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d 61  ory..** Since ma
18910 6e 79 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75  ny statement jou
18920 72 6e 61 6c 73 20 6e 65 76 65 72 20 62 65 63 6f  rnals never beco
18930 6d 65 20 6c 61 72 67 65 2c 20 73 65 74 74 69 6e  me large, settin
18940 67 20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a 20 74  g the spill.** t
18950 68 72 65 73 68 6f 6c 64 20 74 6f 20 61 20 76 61  hreshold to a va
18960 6c 75 65 20 73 75 63 68 20 61 73 20 36 34 4b 69  lue such as 64Ki
18970 42 20 63 61 6e 20 67 72 65 61 74 6c 79 20 72 65  B can greatly re
18980 64 75 63 65 20 74 68 65 20 61 6d 6f 75 6e 74 20  duce the amount 
18990 6f 66 0a 2a 2a 20 49 2f 4f 20 72 65 71 75 69 72  of.** I/O requir
189a0 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 73 74  ed to support st
189b0 61 74 65 6d 65 6e 74 20 72 6f 6c 6c 62 61 63 6b  atement rollback
189c0 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74  ..** The default
189d0 20 76 61 6c 75 65 20 66 6f 72 20 74 68 69 73 20   value for this 
189e0 73 65 74 74 69 6e 67 20 69 73 20 63 6f 6e 74 72  setting is contr
189f0 6f 6c 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  olled by the.** 
18a00 5b 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52 4e 4c  [SQLITE_STMTJRNL
18a10 5f 53 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65 2d  _SPILL] compile-
18a20 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  time option..** 
18a30 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
18a40 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
18a50 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20  INGLETHREAD  1  
18a60 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
18a70 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18a80 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20  MULTITHREAD   2 
18a90 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
18aa0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18ab0 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33  _SERIALIZED    3
18ac0 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
18ad0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18ae0 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20  G_MALLOC        
18af0 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  4  /* sqlite3_me
18b00 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
18b10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
18b20 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20  FIG_GETMALLOC   
18b30 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    5  /* sqlite3_
18b40 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
18b50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18b60 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20  ONFIG_SCRATCH   
18b70 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c      6  /* void*,
18b80 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a   int sz, int N *
18b90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18ba0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
18bb0 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64  E     7  /* void
18bc0 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
18bd0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18be0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20  TE_CONFIG_HEAP  
18bf0 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f          8  /* vo
18c00 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  id*, int nByte, 
18c10 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69  int min */.#defi
18c20 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18c30 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39  _MEMSTATUS     9
18c40 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a    /* boolean */.
18c50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18c60 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20  ONFIG_MUTEX     
18c70 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65     10  /* sqlite
18c80 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
18c90 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18ca0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
18cb0 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71  EX     11  /* sq
18cc0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
18cd0 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69  ods* */./* previ
18ce0 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e  ously SQLITE_CON
18cf0 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31  FIG_CHUNKALLOC 1
18d00 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75  2 which is now u
18d10 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69  nused. */ .#defi
18d20 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18d30 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33  _LOOKASIDE    13
18d40 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a    /* int int */.
18d50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18d60 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20  ONFIG_PCACHE    
18d70 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20     14  /* no-op 
18d80 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18d90 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
18da0 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d  HE    15  /* no-
18db0 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  op */.#define SQ
18dc0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
18dd0 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20           16  /* 
18de0 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a  xFunc, void* */.
18df0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18e00 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20  ONFIG_URI       
18e10 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f     17  /* int */
18e20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18e30 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20  CONFIG_PCACHE2  
18e40 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74      18  /* sqlit
18e50 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
18e60 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  s2* */.#define S
18e70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
18e80 50 43 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a  PCACHE2   19  /*
18e90 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f   sqlite3_pcache_
18ea0 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65  methods2* */.#de
18eb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18ec0 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
18ed0 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e  X_SCAN 20  /* in
18ee0 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
18ef0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f  ITE_CONFIG_SQLLO
18f00 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78  G       21  /* x
18f10 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f  Sqllog, void* */
18f20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18f30 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
18f40 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74      22  /* sqlit
18f50 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65  e3_int64, sqlite
18f60 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69  3_int64 */.#defi
18f70 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18f80 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20  _WIN32_HEAPSIZE 
18f90 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74 20       23  /* int 
18fa0 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  nByte */.#define
18fb0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
18fc0 43 41 43 48 45 5f 48 44 52 53 5a 20 20 20 20 20  CACHE_HDRSZ     
18fd0 20 20 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a 70     24  /* int *p
18fe0 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  sz */.#define SQ
18ff0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53  LITE_CONFIG_PMAS
19000 5a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Z               
19010 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e 65 64 20  25  /* unsigned 
19020 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a 23 64 65  int szPma */.#de
19030 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
19040 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c  IG_STMTJRNL_SPIL
19050 4c 20 20 20 20 20 20 32 36 20 20 2f 2a 20 69 6e  L      26  /* in
19060 74 20 6e 42 79 74 65 20 2a 2f 0a 0a 2f 2a 0a 2a  t nByte */../*.*
19070 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
19080 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
19090 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
190a0 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
190b0 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
190c0 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
190d0 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
190e0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
190f0 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
19100 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
19110 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
19120 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
19130 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
19140 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
19150 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
19160 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
19170 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
19180 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
19190 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
191a0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
191b0 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
191c0 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
191d0 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
191e0 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
191f0 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
19200 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  _db_config()] to
19210 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
19220 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
19230 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74  ed.  ^The [sqlit
19240 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
19250 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
19260 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
19270 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
19280 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
19290 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
192a0 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
192b0 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
192c0 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
192d0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
192e0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
192f0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
19300 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
19310 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e  s three addition
19320 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  al arguments tha
19330 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
19340 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d  .** [lookaside m
19350 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d  emory allocator]
19360 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
19370 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  or the [database
19380 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
19390 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
193a0 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20  ment (the third 
193b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
193c0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
193d0 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74  )] is a.** point
193e0 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62  er to a memory b
193f0 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72  uffer to use for
19400 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
19410 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  y..** ^The first
19420 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20   argument after 
19430 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  the SQLITE_DBCON
19440 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65  FIG_LOOKASIDE ve
19450 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c  rb.** may be NUL
19460 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  L in which case 
19470 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f  SQLite will allo
19480 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b  cate the.** look
19490 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73  aside buffer its
194a0 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  elf using [sqlit
194b0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54  e3_malloc()]. ^T
194c0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
194d0 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
194e0 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
194f0 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e  ide buffer slot.
19500 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67    ^The third arg
19510 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d  ument is the num
19520 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e  ber of.** slots.
19530 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
19540 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20  e buffer in the 
19550 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
19560 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74  ust be greater t
19570 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20  han.** or equal 
19580 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f  to the product o
19590 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  f the second and
195a0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73   third arguments
195b0 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a  .  The buffer.**
195c0 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
195d0 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
195e0 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65  undary.  ^If the
195f0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
19600 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42   to.** SQLITE_DB
19610 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
19620 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70   is not a multip
19630 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69  le of 8, it is i
19640 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75  nternally.** rou
19650 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65  nded down to the
19660 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75   next smaller mu
19670 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28  ltiple of 8.  ^(
19680 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  The lookaside me
19690 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  mory.** configur
196a0 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61  ation for a data
196b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
196c0 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e  can only be chan
196d0 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a  ged when that.**
196e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e   connection is n
196f0 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69  ot currently usi
19700 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  ng lookaside mem
19710 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72  ory, or in other
19720 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74   words.** when t
19730 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75  he "current valu
19740 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  e" returned by.*
19750 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74  * [sqlite3_db_st
19760 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f  atus](D,[SQLITE_
19770 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
19780 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a  ],...) is zero..
19790 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
197a0 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f  o change the loo
197b0 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f  kaside memory co
197c0 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e  nfiguration when
197d0 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65   lookaside.** me
197e0 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c  mory is in use l
197f0 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67  eaves the config
19800 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65  uration unchange
19810 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a  d and returns .*
19820 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e  * [SQLITE_BUSY].
19830 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  )^</dd>.**.** <d
19840 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
19850 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64  G_ENABLE_FKEY</d
19860 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
19870 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
19880 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
19890 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65  able the enforce
198a0 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65  ment of.** [fore
198b0 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69  ign key constrai
198c0 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f  nts].  There sho
198d0 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
198e0 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
198f0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
19900 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
19910 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
19920 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e  to disable FK en
19930 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f  forcement,.** po
19940 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
19950 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
19960 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
19970 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  eave FK enforcem
19980 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64  ent.** unchanged
19990 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
199a0 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
199b0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
199c0 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
199d0 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
199e0 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
199f0 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63  hether FK enforc
19a00 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20  ement is off or 
19a10 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  on.** following 
19a20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
19a30 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
19a40 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
19a50 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
19a60 69 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20  ich case the FK 
19a70 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74  enforcement sett
19a80 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
19a90 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
19aa0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
19ab0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
19ac0 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a  _TRIGGER</dt>.**
19ad0 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
19ae0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
19af0 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
19b00 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
19b10 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20  | triggers]..** 
19b20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
19b30 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
19b40 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
19b50 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
19b60 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
19b70 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
19b80 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a  ble triggers,.**
19b90 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
19ba0 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20  ble triggers or 
19bb0 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76  negative to leav
19bc0 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e  e the setting un
19bd0 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20  changed..** The 
19be0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
19bf0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
19c00 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
19c10 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
19c20 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
19c30 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
19c40 74 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73  triggers are dis
19c50 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64  abled or enabled
19c60 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
19c70 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
19c80 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
19c90 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
19ca0 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
19cb0 68 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67  h case the trigg
19cc0 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  er setting is no
19cd0 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
19ce0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
19cf0 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
19d00 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b  _ENABLE_FTS3_TOK
19d10 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  ENIZER</dt>.** <
19d20 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
19d30 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
19d40 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  le or disable th
19d50 65 20 74 77 6f 2d 61 72 67 75 6d 65 6e 74 0a 2a  e two-argument.*
19d60 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  * version of the
19d70 20 5b 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72   [fts3_tokenizer
19d80 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77 68 69  ()] function whi
19d90 63 68 20 69 73 20 70 61 72 74 20 6f 66 20 74 68  ch is part of th
19da0 65 0a 2a 2a 20 5b 46 54 53 33 5d 20 66 75 6c 6c  e.** [FTS3] full
19db0 2d 74 65 78 74 20 73 65 61 72 63 68 20 65 6e 67  -text search eng
19dc0 69 6e 65 20 65 78 74 65 6e 73 69 6f 6e 2e 0a 2a  ine extension..*
19dd0 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62  * There should b
19de0 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
19df0 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54   arguments..** T
19e00 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
19e10 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  t is an integer 
19e20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69  which is 0 to di
19e30 73 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e  sable fts3_token
19e40 69 7a 65 72 28 29 20 6f 72 0a 2a 2a 20 70 6f 73  izer() or.** pos
19e50 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
19e60 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29  fts3_tokenizer()
19e70 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
19e80 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e  leave the settin
19e90 67 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 0a  g.** unchanged..
19ea0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
19eb0 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
19ec0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
19ed0 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
19ee0 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
19ef0 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
19f00 68 65 74 68 65 72 20 66 74 73 33 5f 74 6f 6b 65  hether fts3_toke
19f10 6e 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65  nizer is disable
19f20 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20  d or enabled.** 
19f30 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
19f40 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
19f50 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
19f60 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
19f70 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61  , in.** which ca
19f80 73 65 20 74 68 65 20 6e 65 77 20 73 65 74 74 69  se the new setti
19f90 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
19fa0 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
19fb0 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  *.** </dl>.*/.#d
19fc0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
19fd0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
19fe0 20 20 20 20 20 20 20 20 20 20 20 20 31 30 30 31              1001
19ff0 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e   /* void* int in
1a000 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
1a010 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
1a020 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 20 20 20  BLE_FKEY        
1a030 20 20 20 31 30 30 32 20 2f 2a 20 69 6e 74 20 69     1002 /* int i
1a040 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nt* */.#define S
1a050 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
1a060 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20 20 20  NABLE_TRIGGER   
1a070 20 20 20 20 20 31 30 30 33 20 2f 2a 20 69 6e 74       1003 /* int
1a080 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
1a090 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
1a0a0 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b  _ENABLE_FTS3_TOK
1a0b0 45 4e 49 5a 45 52 20 31 30 30 34 20 2f 2a 20 69  ENIZER 1004 /* i
1a0c0 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a  nt int* */.../*.
1a0d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
1a0e0 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45  ble Or Disable E
1a0f0 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
1a100 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  odes.** METHOD: 
1a110 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
1a120 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  he sqlite3_exten
1a130 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
1a140 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c  () routine enabl
1a150 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
1a160 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  he.** [extended 
1a170 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65  result codes] fe
1a180 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e  ature of SQLite.
1a190 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72   ^The extended r
1a1a0 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61  esult.** codes a
1a1b0 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
1a1c0 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f  efault for histo
1a1d0 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c  rical compatibil
1a1e0 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ity..*/.SQLITE_A
1a1f0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
1a200 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 78  DCALL sqlite3_ex
1a210 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
1a220 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  des(sqlite3*, in
1a230 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a  t onoff);../*.**
1a240 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20   CAPI3REF: Last 
1a250 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 20  Insert Rowid.** 
1a260 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1a270 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72  **.** ^Each entr
1a280 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65  y in most SQLite
1a290 20 74 61 62 6c 65 73 20 28 65 78 63 65 70 74 20   tables (except 
1a2a0 66 6f 72 20 5b 57 49 54 48 4f 55 54 20 52 4f 57  for [WITHOUT ROW
1a2b0 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68  ID] tables).** h
1a2c0 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62  as a unique 64-b
1a2d0 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74  it signed.** int
1a2e0 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20  eger key called 
1a2f0 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f  the [ROWID | "ro
1a300 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69  wid"]. ^The rowi
1a310 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69  d is always avai
1a320 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75  lable.** as an u
1a330 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e  ndeclared column
1a340 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49   named ROWID, OI
1a350 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73  D, or _ROWID_ as
1a360 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a   long as those.*
1a370 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20  * names are not 
1a380 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70  also used by exp
1a390 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
1a3a0 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a   columns. ^If.**
1a3b0 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61   the table has a
1a3c0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20   column of type 
1a3d0 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59  [INTEGER PRIMARY
1a3e0 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20   KEY] then that 
1a3f0 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f  column.** is ano
1a400 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74  ther alias for t
1a410 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20  he rowid..**.** 
1a420 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 73  ^The sqlite3_las
1a430 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44  t_insert_rowid(D
1a440 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
1a450 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20  rns the [rowid] 
1a460 6f 66 20 74 68 65 20 0a 2a 2a 20 6d 6f 73 74 20  of the .** most 
1a470 72 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75  recent successfu
1a480 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20  l [INSERT] into 
1a490 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72  a rowid table or
1a4a0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
1a4b0 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20  .** on database 
1a4c0 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a  connection D..**
1a4d0 20 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b   ^Inserts into [
1a4e0 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74  WITHOUT ROWID] t
1a4f0 61 62 6c 65 73 20 61 72 65 20 6e 6f 74 20 72 65  ables are not re
1a500 63 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e  corded..** ^If n
1a510 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  o successful [IN
1a520 53 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69  SERT]s into rowi
1a530 64 20 74 61 62 6c 65 73 0a 2a 2a 20 68 61 76 65  d tables.** have
1a540 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f   ever occurred o
1a550 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
1a560 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a  onnection D, .**
1a570 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61   then sqlite3_la
1a580 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1a590 44 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  D) returns zero.
1a5a0 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b  .**.** ^(If an [
1a5b0 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77  INSERT] occurs w
1a5c0 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20  ithin a trigger 
1a5d0 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72  or within a [vir
1a5e0 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d  tual table].** m
1a5f0 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73  ethod, then this
1a600 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65   routine will re
1a610 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d  turn the [rowid]
1a620 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64   of the inserted
1a630 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20  .** row as long 
1a640 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20 6f  as the trigger o
1a650 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  r virtual table 
1a660 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e  method is runnin
1a670 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74  g..** But once t
1a680 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  he trigger or vi
1a690 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68  rtual table meth
1a6a0 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c  od ends, the val
1a6b0 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20  ue returned .** 
1a6c0 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  by this routine 
1a6d0 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 20  reverts to what 
1a6e0 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 68  it was before th
1a6f0 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72  e trigger or vir
1a700 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65  tual.** table me
1a710 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a  thod began.)^.**
1a720 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d  .** ^An [INSERT]
1a730 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20   that fails due 
1a740 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  to a constraint 
1a750 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74  violation is not
1a760 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c   a.** successful
1a770 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f   [INSERT] and do
1a780 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
1a790 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1a7a0 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   by this.** rout
1a7b0 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45  ine.  ^Thus INSE
1a7c0 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45  RT OR FAIL, INSE
1a7d0 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e  RT OR IGNORE, IN
1a7e0 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b  SERT OR ROLLBACK
1a7f0 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20  ,.** and INSERT 
1a800 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f  OR ABORT make no
1a810 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
1a820 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
1a830 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  this.** routine 
1a840 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72  when their inser
1a850 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57  tion fails.  ^(W
1a860 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45  hen INSERT OR RE
1a870 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74  PLACE.** encount
1a880 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74  ers a constraint
1a890 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64   violation, it d
1a8a0 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54  oes not fail.  T
1a8b0 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e  he.** INSERT con
1a8c0 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65  tinues to comple
1a8d0 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74  tion after delet
1a8e0 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61  ing rows that ca
1a8f0 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73  used.** the cons
1a900 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73  traint problem s
1a910 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  o INSERT OR REPL
1a920 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ACE will always 
1a930 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65  change.** the re
1a940 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
1a950 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a  is interface.)^.
1a960 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70  **.** ^For the p
1a970 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20  urposes of this 
1a980 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53  routine, an [INS
1a990 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72  ERT] is consider
1a9a0 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63  ed to.** be succ
1a9b0 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69  essful even if i
1a9c0 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c  t is subsequentl
1a9d0 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  y rolled back..*
1a9e0 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
1a9f0 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65  on is accessible
1aa00 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   to SQL statemen
1aa10 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c  ts via the.** [l
1aa20 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
1aa30 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
1aa40 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
1aa50 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72  arate thread per
1aa60 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53  forms a new [INS
1aa70 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65  ERT] on the same
1aa80 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
1aa90 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68  nection while th
1aaa0 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  e [sqlite3_last_
1aab0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a  insert_rowid()].
1aac0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ** function is r
1aad0 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20  unning and thus 
1aae0 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74  changes the last
1aaf0 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c   insert [rowid],
1ab00 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c  .** then the val
1ab10 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ue returned by [
1ab20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
1ab30 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a  ert_rowid()] is.
1ab40 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  ** unpredictable
1ab50 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65   and might not e
1ab60 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20  qual either the 
1ab70 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a  old or the new.*
1ab80 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72  * last insert [r
1ab90 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  owid]..*/.SQLITE
1aba0 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74  _API sqlite3_int
1abb0 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  64 SQLITE_STDCAL
1abc0 4c 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  L sqlite3_last_i
1abd0 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69  nsert_rowid(sqli
1abe0 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
1abf0 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68  PI3REF: Count Th
1ac00 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  e Number Of Rows
1ac10 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54   Modified.** MET
1ac20 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1ac30 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
1ac40 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
1ac50 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64  mber of rows mod
1ac60 69 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20  ified, inserted 
1ac70 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79  or.** deleted by
1ac80 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
1ac90 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53  ly completed INS
1aca0 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
1acb0 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65  ELETE.** stateme
1acc0 6e 74 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  nt on the databa
1acd0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70  se connection sp
1ace0 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f  ecified by the o
1acf0 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  nly parameter..*
1ad00 2a 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79  * ^Executing any
1ad10 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53   other type of S
1ad20 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
1ad30 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65  s not modify the
1ad40 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
1ad50 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74  ed by this funct
1ad60 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79  ion..**.** ^Only
1ad70 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69   changes made di
1ad80 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e  rectly by the IN
1ad90 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
1ada0 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
1adb0 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72   are.** consider
1adc0 65 64 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63  ed - auxiliary c
1add0 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
1ade0 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
1adf0 20 7c 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a   | triggers], .*
1ae00 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  * [foreign key a
1ae10 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c  ctions] or [REPL
1ae20 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20  ACE] constraint 
1ae30 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e  resolution are n
1ae40 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a  ot counted..** .
1ae50 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20  ** Changes to a 
1ae60 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e  view that are in
1ae70 74 65 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a  tercepted by .**
1ae80 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
1ae90 67 67 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f  gger | INSTEAD O
1aea0 46 20 74 72 69 67 67 65 72 73 5d 20 61 72 65 20  F triggers] are 
1aeb0 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68  not counted. ^Th
1aec0 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75  e value .** retu
1aed0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
1aee0 63 68 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69  changes() immedi
1aef0 61 74 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49  ately after an I
1af00 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
1af10 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74   .** DELETE stat
1af20 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76  ement run on a v
1af30 69 65 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65  iew is always ze
1af40 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73  ro. Only changes
1af50 20 6d 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a   made to real .*
1af60 2a 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75  * tables are cou
1af70 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e  nted..**.** Thin
1af80 67 73 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70  gs are more comp
1af90 6c 69 63 61 74 65 64 20 69 66 20 74 68 65 20 73  licated if the s
1afa0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
1afb0 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20   function is.** 
1afc0 65 78 65 63 75 74 65 64 20 77 68 69 6c 65 20 61  executed while a
1afd0 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
1afe0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69   is running. Thi
1aff0 73 20 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20  s may happen if 
1b000 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  the.** program u
1b010 73 65 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73  ses the [changes
1b020 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
1b030 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68  , or if some oth
1b040 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  er callback.** f
1b050 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20  unction invokes 
1b060 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1b070 29 20 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65  ) directly. Esse
1b080 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20  ntially:.** .** 
1b090 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e  <ul>.**   <li> ^
1b0a0 28 42 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67  (Before entering
1b0b0 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72   a trigger progr
1b0c0 61 6d 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  am the value ret
1b0d0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  urned by.**     
1b0e0 20 20 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67     sqlite3_chang
1b0f0 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  es() function is
1b100 20 73 61 76 65 64 2e 20 41 66 74 65 72 20 74 68   saved. After th
1b110 65 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  e trigger progra
1b120 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73  m .**        has
1b130 20 66 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f   finished, the o
1b140 72 69 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73  riginal value is
1b150 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20   restored.)^.** 
1b160 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74  .**   <li> ^(Wit
1b170 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 70 72  hin a trigger pr
1b180 6f 67 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52  ogram each INSER
1b190 54 2c 20 55 50 44 41 54 45 20 61 6e 64 20 44 45  T, UPDATE and DE
1b1a0 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20  LETE .**        
1b1b0 73 74 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74  statement sets t
1b1c0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1b1d0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61  d by sqlite3_cha
1b1e0 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20  nges() .**      
1b1f0 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f    upon completio
1b200 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20  n as normal. Of 
1b210 63 6f 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c  course, this val
1b220 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c  ue will not incl
1b230 75 64 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61  ude .**        a
1b240 6e 79 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f  ny changes perfo
1b250 72 6d 65 64 20 62 79 20 73 75 62 2d 74 72 69 67  rmed by sub-trig
1b260 67 65 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c  gers, as the sql
1b270 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a  ite3_changes() .
1b280 2a 2a 20 20 20 20 20 20 20 20 76 61 6c 75 65 20  **        value 
1b290 77 69 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e  will be saved an
1b2a0 64 20 72 65 73 74 6f 72 65 64 20 61 66 74 65 72  d restored after
1b2b0 20 65 61 63 68 20 73 75 62 2d 74 72 69 67 67 65   each sub-trigge
1b2c0 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20  r has run.)^.** 
1b2d0 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68  </ul>.** .** ^Th
1b2e0 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66  is means that if
1b2f0 20 74 68 65 20 63 68 61 6e 67 65 73 28 29 20 53   the changes() S
1b300 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20  QL function (or 
1b310 73 69 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64  similar) is used
1b320 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73 74  .** by the first
1b330 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
1b340 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
1b350 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69  ent within a tri
1b360 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74  gger, it .** ret
1b370 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61  urns the value a
1b380 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 63  s set when the c
1b390 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  alling statement
1b3a0 20 62 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67   began executing
1b3b0 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75  ..** ^If it is u
1b3c0 73 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  sed by the secon
1b3d0 64 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  d or subsequent 
1b3e0 73 75 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77  such statement w
1b3f0 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20  ithin a trigger 
1b400 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65  .** program, the
1b410 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1b420 72 65 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d  reflects the num
1b430 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69  ber of rows modi
1b440 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20  fied by the .** 
1b450 70 72 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c  previous INSERT,
1b460 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
1b470 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  E statement with
1b480 69 6e 20 74 68 65 20 73 61 6d 65 20 74 72 69 67  in the same trig
1b490 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ger..**.** See a
1b4a0 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
1b4b0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
1b4c0 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  ] interface, the
1b4d0 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67  .** [count_chang
1b4e0 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20  es pragma], and 
1b4f0 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53  the [changes() S
1b500 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
1b510 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
1b520 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
1b530 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
1b540 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
1b550 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
1b560 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
1b570 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
1b580 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
1b590 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70  turned.** is unp
1b5a0 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
1b5b0 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
1b5c0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
1b5d0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
1b5e0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1b5f0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
1b600 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61  * CAPI3REF: Tota
1b610 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  l Number Of Rows
1b620 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54   Modified.** MET
1b630 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1b640 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
1b650 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f  n returns the to
1b660 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  tal number of ro
1b670 77 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64  ws inserted, mod
1b680 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65  ified or.** dele
1b690 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45  ted by all [INSE
1b6a0 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72  RT], [UPDATE] or
1b6b0 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d   [DELETE] statem
1b6c0 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a  ents completed.*
1b6d0 2a 20 73 69 6e 63 65 20 74 68 65 20 64 61 74 61  * since the data
1b6e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1b6f0 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c  was opened, incl
1b700 75 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65 63  uding those exec
1b710 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20  uted as.** part 
1b720 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f 67 72  of trigger progr
1b730 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67 20  ams. ^Executing 
1b740 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f  any other type o
1b750 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a  f SQL statement.
1b760 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66 65  ** does not affe
1b770 63 74 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ct the value ret
1b780 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
1b790 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
1b7a0 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65  ..** .** ^Change
1b7b0 73 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f  s made as part o
1b7c0 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  f [foreign key a
1b7d0 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c  ctions] are incl
1b7e0 75 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63  uded in the.** c
1b7f0 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65 20  ount, but those 
1b800 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20  made as part of 
1b810 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69  REPLACE constrai
1b820 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72  nt resolution ar
1b830 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67  e.** not. ^Chang
1b840 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61  es to a view tha
1b850 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65  t are intercepte
1b860 64 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46 20  d by INSTEAD OF 
1b870 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72 65  triggers .** are
1b880 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a   not counted..**
1b890 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68   .** See also th
1b8a0 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
1b8b0 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  es()] interface,
1b8c0 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
1b8d0 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20  hanges pragma], 
1b8e0 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63  and the [total_c
1b8f0 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
1b900 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
1b910 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
1b920 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
1b930 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
1b940 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1b950 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
1b960 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
1b970 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
1b980 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a  hen the value.**
1b990 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70   returned is unp
1b9a0 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
1b9b0 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
1b9c0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
1b9d0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
1b9e0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
1b9f0 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
1ba00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1ba10 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f  : Interrupt A Lo
1ba20 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79  ng-Running Query
1ba30 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1ba40 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  te3.**.** ^This 
1ba50 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
1ba60 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61  any pending data
1ba70 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74  base operation t
1ba80 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72  o abort and.** r
1ba90 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72  eturn at its ear
1baa0 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74  liest opportunit
1bab0 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  y. This routine 
1bac0 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20  is typically.** 
1bad0 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e  called in respon
1bae0 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74  se to a user act
1baf0 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73  ion such as pres
1bb00 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a  sing "Cancel".**
1bb10 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65   or Ctrl-C where
1bb20 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20   the user wants 
1bb30 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65  a long query ope
1bb40 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a  ration to halt.*
1bb50 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  * immediately..*
1bb60 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65  *.** ^It is safe
1bb70 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
1bb80 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72  utine from a thr
1bb90 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72  ead different fr
1bba0 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64  om the.** thread
1bbb0 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74   that is current
1bbc0 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64  ly running the d
1bbd0 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
1bbe0 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73  n.  But it.** is
1bbf0 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c   not safe to cal
1bc00 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  l this routine w
1bc10 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
1bc20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
1bc30 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72  .** is closed or
1bc40 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66   might close bef
1bc50 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  ore sqlite3_inte
1bc60 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e  rrupt() returns.
1bc70 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51  .**.** ^If an SQ
1bc80 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76  L operation is v
1bc90 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73  ery nearly finis
1bca0 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20  hed at the time 
1bcb0 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  when.** sqlite3_
1bcc0 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63  interrupt() is c
1bcd0 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d  alled, then it m
1bce0 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e  ight not have an
1bcf0 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20   opportunity.** 
1bd00 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65  to be interrupte
1bd10 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74  d and might cont
1bd20 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69  inue to completi
1bd30 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51  on..**.** ^An SQ
1bd40 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74  L operation that
1bd50 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20   is interrupted 
1bd60 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
1bd70 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a  ITE_INTERRUPT]..
1bd80 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72  ** ^If the inter
1bd90 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61  rupted SQL opera
1bda0 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52  tion is an INSER
1bdb0 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
1bdc0 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20  LETE.** that is 
1bdd0 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63  inside an explic
1bde0 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
1bdf0 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20  then the entire 
1be00 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77  transaction.** w
1be10 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ill be rolled ba
1be20 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
1be30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1be40 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
1be50 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66  ) call is in eff
1be60 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75  ect until all cu
1be70 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a  rrently running.
1be80 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
1be90 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
1bea0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d  onnection] D com
1beb0 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77  plete.  ^Any new
1bec0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
1bed0 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
1bee0 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71  ted after the sq
1bef0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1bf00 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72  ) call and befor
1bf10 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e  e the .** runnin
1bf20 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61  g statements rea
1bf30 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e  ches zero are in
1bf40 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20  terrupted as if 
1bf50 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a  they had been.**
1bf60 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74   running prior t
1bf70 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  o the sqlite3_in
1bf80 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20  terrupt() call. 
1bf90 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d   ^New SQL statem
1bfa0 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
1bfb0 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
1bfc0 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  he running state
1bfd0 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68  ment count reach
1bfe0 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e  es zero are.** n
1bff0 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74  ot effected by t
1c000 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
1c010 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61  rupt()..** ^A ca
1c020 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
1c030 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20  terrupt(D) that 
1c040 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72  occurs when ther
1c050 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67  e are no running
1c060 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1c070 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e  ts is a no-op an
1c080 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20  d has no effect 
1c090 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  on SQL statement
1c0a0 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
1c0b0 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
1c0c0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1c0d0 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  t() call returns
1c0e0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64  ..**.** If the d
1c0f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1c100 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20  on closes while 
1c110 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
1c120 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e  pt()].** is runn
1c130 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69  ing then bad thi
1c140 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ngs will likely 
1c150 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54  happen..*/.SQLIT
1c160 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54  E_API void SQLIT
1c170 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
1c180 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69  3_interrupt(sqli
1c190 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
1c1a0 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
1c1b0 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
1c1c0 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74  ement Is Complet
1c1d0 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  e.**.** These ro
1c1e0 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75  utines are usefu
1c1f0 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64  l during command
1c200 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64  -line input to d
1c210 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a  etermine if the.
1c220 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74  ** currently ent
1c230 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20  ered text seems 
1c240 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65  to form a comple
1c250 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
1c260 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69   or.** if additi
1c270 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65  onal input is ne
1c280 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64  eded before send
1c290 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74  ing the text int
1c2a0 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20  o.** SQLite for 
1c2b0 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65  parsing.  ^These
1c2c0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1c2d0 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20   1 if the input 
1c2e0 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72  string.** appear
1c2f0 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65  s to be a comple
1c300 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
1c310 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20  .  ^A statement 
1c320 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a  is judged to be.
1c330 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69  ** complete if i
1c340 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65  t ends with a se
1c350 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e  micolon token an
1c360 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69  d is not a prefi
1c370 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66  x of a.** well-f
1c380 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49  ormed CREATE TRI
1c390 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20  GGER statement. 
1c3a0 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61   ^Semicolons tha
1c3b0 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77  t are embedded w
1c3c0 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20  ithin.** string 
1c3d0 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74  literals or quot
1c3e0 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61  ed identifier na
1c3f0 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20  mes or comments 
1c400 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70  are not.** indep
1c410 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74  endent tokens (t
1c420 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20  hey are part of 
1c430 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69  the token in whi
1c440 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65  ch they are.** e
1c450 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75  mbedded) and thu
1c460 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
1c470 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65  s a statement te
1c480 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74  rminator.  ^Whit
1c490 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f  espace.** and co
1c4a0 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c  mments that foll
1c4b0 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d  ow the final sem
1c4c0 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72  icolon are ignor
1c4d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
1c4e0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1c4f0 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d   0 if the statem
1c500 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74  ent is incomplet
1c510 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d  e.  ^If a.** mem
1c520 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
1c530 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54  ails, then SQLIT
1c540 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72  E_NOMEM is retur
1c550 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ned..**.** ^Thes
1c560 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f  e routines do no
1c570 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20  t parse the SQL 
1c580 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a  statements thus.
1c590 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65  ** will not dete
1c5a0 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79  ct syntactically
1c5b0 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a   incorrect SQL..
1c5c0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74  **.** ^(If SQLit
1c5d0 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69  e has not been i
1c5e0 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67  nitialized using
1c5f0 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
1c600 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a  lize()] prior .*
1c610 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71  * to invoking sq
1c620 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
1c630 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  () then sqlite3_
1c640 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
1c650 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d  invoked.** autom
1c660 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
1c670 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
1c680 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69  .  If that initi
1c690 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c  alization fails,
1c6a0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74  .** then the ret
1c6b0 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
1c6c0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
1c6d0 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d  6() will be non-
1c6e0 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65  zero.** regardle
1c6f0 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
1c700 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53   not the input S
1c710 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29  QL is complete.)
1c720 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ^.**.** The inpu
1c730 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
1c740 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62  mplete()] must b
1c750 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
1c760 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72  ted.** UTF-8 str
1c770 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ing..**.** The i
1c780 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
1c790 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d  _complete16()] m
1c7a0 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
1c7b0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
1c7c0 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74  16 string in nat
1c7d0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
1c7e0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
1c7f0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
1c800 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
1c810 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  e(const char *sq
1c820 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  l);.SQLITE_API i
1c830 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
1c840 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  L sqlite3_comple
1c850 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20  te16(const void 
1c860 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  *sql);../*.** CA
1c870 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72  PI3REF: Register
1c880 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48   A Callback To H
1c890 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53  andle SQLITE_BUS
1c8a0 59 20 45 72 72 6f 72 73 0a 2a 2a 20 4b 45 59 57  Y Errors.** KEYW
1c8b0 4f 52 44 53 3a 20 7b 62 75 73 79 2d 68 61 6e 64  ORDS: {busy-hand
1c8c0 6c 65 72 20 63 61 6c 6c 62 61 63 6b 7d 20 7b 62  ler callback} {b
1c8d0 75 73 79 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20  usy handler}.** 
1c8e0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1c8f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1c900 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1c910 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65 20 73  D,X,P) routine s
1c920 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ets a callback f
1c930 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61  unction X.** tha
1c940 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  t might be invok
1c950 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ed with argument
1c960 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61   P whenever.** a
1c970 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64  n attempt is mad
1c980 65 20 74 6f 20 61 63 63 65 73 73 20 61 20 64 61  e to access a da
1c990 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 73 73  tabase table ass
1c9a0 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20  ociated with.** 
1c9b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1c9c0 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f  tion] D when ano
1c9d0 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f  ther thread.** o
1c9e0 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 74 68  r process has th
1c9f0 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a  e table locked..
1ca00 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62  ** The sqlite3_b
1ca10 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e  usy_handler() in
1ca20 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
1ca30 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20  to implement.** 
1ca40 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
1ca50 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50 52  meout()] and [PR
1ca60 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75  AGMA busy_timeou
1ca70 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  t]..**.** ^If th
1ca80 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
1ca90 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53  is NULL, then [S
1caa0 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69  QLITE_BUSY].** i
1cab0 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
1cac0 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f  iately upon enco
1cad0 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63  untering the loc
1cae0 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79  k.  ^If the busy
1caf0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
1cb00 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  not NULL, then t
1cb10 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68  he callback migh
1cb20 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  t be invoked wit
1cb30 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e  h two arguments.
1cb40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
1cb50 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
1cb60 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  e busy handler i
1cb70 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
1cb80 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68  void* pointer wh
1cb90 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68  ich.** is the th
1cba0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
1cbb0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1cbc0 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65  dler().  ^The se
1cbd0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
1cbe0 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e  .** the busy han
1cbf0 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  dler callback is
1cc00 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74   the number of t
1cc10 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75  imes that the bu
1cc20 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a  sy handler has.*
1cc30 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 70  * been invoked p
1cc40 72 65 76 69 6f 75 73 6c 79 20 66 6f 72 20 74 68  reviously for th
1cc50 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65  e same locking e
1cc60 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
1cc70 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  * busy callback 
1cc80 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20  returns 0, then 
1cc90 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74  no additional at
1cca0 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20  tempts are made 
1ccb0 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65  to.** access the
1ccc0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53   database and [S
1ccd0 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 20 72  QLITE_BUSY] is r
1cce0 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68  eturned.** to th
1ccf0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a  e application..*
1cd00 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61  * ^If the callba
1cd10 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
1cd20 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65  ero, then anothe
1cd30 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20  r attempt.** is 
1cd40 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 74  made to access t
1cd50 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
1cd60 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74  the cycle repeat
1cd70 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65  s..**.** The pre
1cd80 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20  sence of a busy 
1cd90 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74  handler does not
1cda0 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20   guarantee that 
1cdb0 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b  it will be invok
1cdc0 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65  ed.** when there
1cdd0 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74   is lock content
1cde0 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  ion. ^If SQLite 
1cdf0 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20  determines that 
1ce00 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73  invoking the bus
1ce10 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75  y.** handler cou
1ce20 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64  ld result in a d
1ce30 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c  eadlock, it will
1ce40 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65   go ahead and re
1ce50 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  turn [SQLITE_BUS
1ce60 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70  Y].** to the app
1ce70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74 65 61 64  lication instead
1ce80 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65   of invoking the
1ce90 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65   .** busy handle
1cea0 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61  r..** Consider a
1ceb0 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20   scenario where 
1cec0 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68  one process is h
1ced0 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f  olding a read lo
1cee0 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73  ck that.** it is
1cef0 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f   trying to promo
1cf00 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64  te to a reserved
1cf10 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73   lock and.** a s
1cf20 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73  econd process is
1cf30 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72   holding a reser
1cf40 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74  ved lock that it
1cf50 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f   is trying.** to
1cf60 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65   promote to an e
1cf70 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20  xclusive lock.  
1cf80 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  The first proces
1cf90 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64  s cannot proceed
1cfa0 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69  .** because it i
1cfb0 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
1cfc0 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20   second and the 
1cfd0 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63  second process c
1cfe0 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64  annot.** proceed
1cff0 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
1d000 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69  locked by the fi
1d010 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72  rst.  If both pr
1d020 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b  ocesses.** invok
1d030 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  e the busy handl
1d040 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c  ers, neither wil
1d050 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72  l make any progr
1d060 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c  ess.  Therefore,
1d070 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72  .** SQLite retur
1d080 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ns [SQLITE_BUSY]
1d090 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70   for the first p
1d0a0 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74  rocess, hoping t
1d0b0 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c  hat this.** will
1d0c0 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73   induce the firs
1d0d0 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c  t process to rel
1d0e0 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f  ease its read lo
1d0f0 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20  ck and allow.** 
1d100 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
1d110 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a  ss to proceed..*
1d120 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
1d130 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  t busy callback 
1d140 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  is NULL..**.** ^
1d150 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20  (There can only 
1d160 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
1d170 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64   handler defined
1d180 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61   for each.** [da
1d190 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1d1a0 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e  n].  Setting a n
1d1b0 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  ew busy handler 
1d1c0 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72  clears any.** pr
1d1d0 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e  eviously set han
1d1e0 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74  dler.)^  ^Note t
1d1f0 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  hat calling [sql
1d200 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
1d210 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75  t()].** or evalu
1d220 61 74 69 6e 67 20 5b 50 52 41 47 4d 41 20 62 75  ating [PRAGMA bu
1d230 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69  sy_timeout=N] wi
1d240 6c 6c 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  ll change the.**
1d250 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 61 6e   busy handler an
1d260 64 20 74 68 75 73 20 63 6c 65 61 72 20 61 6e 79  d thus clear any
1d270 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20   previously set 
1d280 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
1d290 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c  .** The busy cal
1d2a0 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74  lback should not
1d2b0 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e   take any action
1d2c0 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74  s which modify t
1d2d0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
1d2e0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
1d2f0 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
1d300 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68  handler.  In oth
1d310 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65  er words,.** the
1d320 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
1d330 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 20   not reentrant. 
1d340 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e   Any such action
1d350 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75  s.** result in u
1d360 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
1d370 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79  r..** .** A busy
1d380 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f   handler must no
1d390 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  t close the data
1d3a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1d3b0 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20  ** or [prepared 
1d3c0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
1d3d0 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
1d3e0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c   handler..*/.SQL
1d3f0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
1d400 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
1d410 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1d420 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29  sqlite3*, int(*)
1d430 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69  (void*,int), voi
1d440 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
1d450 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79  3REF: Set A Busy
1d460 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54 48   Timeout.** METH
1d470 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1d480 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
1d490 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f  sets a [sqlite3_
1d4a0 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62  busy_handler | b
1d4b0 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61  usy handler] tha
1d4c0 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20  t sleeps.** for 
1d4d0 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75  a specified amou
1d4e0 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20  nt of time when 
1d4f0 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65  a table is locke
1d500 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72  d.  ^The handler
1d510 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d  .** will sleep m
1d520 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e  ultiple times un
1d530 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73  til at least "ms
1d540 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
1d550 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61  f sleeping.** ha
1d560 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20  ve accumulated. 
1d570 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74   ^After at least
1d580 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
1d590 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a  ds of sleeping,.
1d5a0 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72  ** the handler r
1d5b0 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63  eturns 0 which c
1d5c0 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73  auses [sqlite3_s
1d5d0 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e  tep()] to return
1d5e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
1d5f0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  ]..**.** ^Callin
1d600 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  g this routine w
1d610 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20  ith an argument 
1d620 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
1d630 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75  al to zero.** tu
1d640 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79  rns off all busy
1d650 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a   handlers..**.**
1d660 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
1d670 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
1d680 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  sy handler for a
1d690 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
1d6a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1d6b0 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69 76 65  ion] at any give
1d6c0 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e  n moment.  If an
1d6d0 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
1d6e0 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65  er.** was define
1d6f0 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74  d  (using [sqlit
1d700 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1d710 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  )]) prior to cal
1d720 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ling.** this rou
1d730 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72  tine, that other
1d740 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
1d750 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a   cleared.)^.**.*
1d760 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52  * See also:  [PR
1d770 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75  AGMA busy_timeou
1d780 74 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  t].*/.SQLITE_API
1d790 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
1d7a0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 75 73 79  ALL sqlite3_busy
1d7b0 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33  _timeout(sqlite3
1d7c0 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a  *, int ms);../*.
1d7d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
1d7e0 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65  venience Routine
1d7f0 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75  s For Running Qu
1d800 65 72 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  eries.** METHOD:
1d810 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54   sqlite3.**.** T
1d820 68 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20  his is a legacy 
1d830 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69  interface that i
1d840 73 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20  s preserved for 
1d850 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
1d860 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20  ibility..** Use 
1d870 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
1d880 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65  e is not recomme
1d890 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69  nded..**.** Defi
1d8a0 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73  nition: A <b>res
1d8b0 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73  ult table</b> is
1d8c0 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72   memory data str
1d8d0 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62  ucture created b
1d8e0 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
1d8f0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69  3_get_table()] i
1d900 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73  nterface.  A res
1d910 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64  ult table record
1d920 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  s the.** complet
1d930 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20  e query results 
1d940 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  from one or more
1d950 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20   queries..**.** 
1d960 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70  The table concep
1d970 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d  tually has a num
1d980 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20  ber of rows and 
1d990 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a  columns.  But.**
1d9a0 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61   these numbers a
1d9b0 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74  re not part of t
1d9c0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1d9d0 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a  itself.  These.*
1d9e0 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62  * numbers are ob
1d9f0 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c  tained separatel
1da00 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65  y.  Let N be the
1da10 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a   number of rows.
1da20 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20  ** and M be the 
1da30 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
1da40 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  s..**.** A resul
1da50 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72  t table is an ar
1da60 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
1da70 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
1da80 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73  ed UTF-8 strings
1da90 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28  ..** There are (
1daa0 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20  N+1)*M elements 
1dab0 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54  in the array.  T
1dac0 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74  he first M point
1dad0 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20  ers point.** to 
1dae0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1daf0 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f  strings that  co
1db00 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  ntain the names 
1db10 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a  of the columns..
1db20 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67  ** The remaining
1db30 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69   entries all poi
1db40 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75  nt to query resu
1db50 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65  lts.  NULL value
1db60 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e  s result.** in N
1db70 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41  ULL pointers.  A
1db80 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20  ll other values 
1db90 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46  are in their UTF
1dba0 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  -8 zero-terminat
1dbb0 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70  ed.** string rep
1dbc0 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72  resentation as r
1dbd0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
1dbe0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
1dbf0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  )]..**.** A resu
1dc00 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63  lt table might c
1dc10 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72  onsist of one or
1dc20 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c   more memory all
1dc30 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20  ocations..** It 
1dc40 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70  is not safe to p
1dc50 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  ass a result tab
1dc60 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b  le directly to [
1dc70 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
1dc80 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
1dc90 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61  le should be dea
1dca0 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b  llocated using [
1dcb0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1dcc0 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41  le()]..**.** ^(A
1dcd0 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  s an example of 
1dce0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
1dcf0 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65   format, suppose
1dd00 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a   a query result.
1dd10 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ** is as follows
1dd20 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1dd30 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
1dd40 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20      Name        
1dd50 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  | Age.**        
1dd60 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1dd70 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20  -------.**      
1dd80 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20    Alice       | 
1dd90 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62  43.**        Bob
1dda0 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a           | 28.**
1ddb0 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20          Cindy   
1ddc0 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72      | 21.** </pr
1ddd0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1dde0 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  **.** There are 
1ddf0 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32  two column (M==2
1de00 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73  ) and three rows
1de10 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74   (N==3).  Thus t
1de20 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62  he.** result tab
1de30 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73  le has 8 entries
1de40 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72  .  Suppose the r
1de50 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73  esult table is s
1de60 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61  tored.** in an a
1de70 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73  rray names azRes
1de80 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73  ult.  Then azRes
1de90 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63  ult holds this c
1dea0 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ontent:.**.** <b
1deb0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1dec0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1ded0 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d  lt&#91;0] = "Nam
1dee0 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
1def0 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20  Result&#91;1] = 
1df00 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Age";.**       
1df10 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d   azResult&#91;2]
1df20 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20   = "Alice";.**  
1df30 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1df40 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a  91;3] = "43";.**
1df50 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1df60 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b  &#91;4] = "Bob";
1df70 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1df80 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38  ult&#91;5] = "28
1df90 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1dfa0 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22  esult&#91;6] = "
1dfb0 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20  Cindy";.**      
1dfc0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37    azResult&#91;7
1dfd0 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70  ] = "21";.** </p
1dfe0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1dff0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
1e000 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1e010 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75  ) function evalu
1e020 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  ates one or more
1e030 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
1e040 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74  parated SQL stat
1e050 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65  ements in the ze
1e060 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
1e070 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66  F-8.** string of
1e080 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74   its 2nd paramet
1e090 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  er and returns a
1e0a0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f   result table to
1e0b0 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20   the.** pointer 
1e0c0 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64  given in its 3rd
1e0d0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
1e0e0 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c  * After the appl
1e0f0 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69  ication has fini
1e100 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65  shed with the re
1e110 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65  sult from sqlite
1e120 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a  3_get_table(),.*
1e130 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74  * it must pass t
1e140 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1e150 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
1e160 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20  e3_free_table() 
1e170 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72  in order to.** r
1e180 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
1e190 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f  y that was mallo
1e1a0 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66  ced.  Because of
1e1b0 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20   the way the.** 
1e1c0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1e1d0 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69  )] happens withi
1e1e0 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  n sqlite3_get_ta
1e1f0 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69  ble(), the calli
1e200 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  ng.** function m
1e210 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63  ust not try to c
1e220 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  all [sqlite3_fre
1e230 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20  e()] directly.  
1e240 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  Only.** [sqlite3
1e250 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69  _free_table()] i
1e260 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73  s able to releas
1e270 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
1e280 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79  perly and safely
1e290 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1e2a0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
1e2b0 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70  interface is imp
1e2c0 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72  lemented as a wr
1e2d0 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
1e2e0 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
1e2f0 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  .  The sqlite3_g
1e300 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69  et_table() routi
1e310 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  ne does not have
1e320 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e   access.** to an
1e330 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20  y internal data 
1e340 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51  structures of SQ
1e350 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f  Lite.  It uses o
1e360 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a  nly the public.*
1e370 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69  * interface defi
1e380 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20  ned here.  As a 
1e390 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72  consequence, err
1e3a0 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69  ors that occur i
1e3b0 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72  n the.** wrapper
1e3c0 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f   layer outside o
1e3d0 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b  f the internal [
1e3e0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
1e3f0 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  call are not.** 
1e400 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62  reflected in sub
1e410 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
1e420 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
1e430 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  e()] or.** [sqli
1e440 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
1e450 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
1e460 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
1e470 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1e480 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
1e490 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e  ,          /* An
1e4a0 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a   open database *
1e4b0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1e4c0 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c  zSql,     /* SQL
1e4d0 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
1e4e0 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61   */.  char ***pa
1e4f0 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52  zResult,    /* R
1e500 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75  esults of the qu
1e510 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ery */.  int *pn
1e520 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f  Row,           /
1e530 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
1e540 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20  lt rows written 
1e550 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  here */.  int *p
1e560 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20  nColumn,        
1e570 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
1e580 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74  ult columns writ
1e590 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68  ten here */.  ch
1e5a0 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20  ar **pzErrmsg   
1e5b0 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
1e5c0 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
1e5d0 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .);.SQLITE_API v
1e5e0 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41  oid SQLITE_STDCA
1e5f0 4c 4c 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  LL sqlite3_free_
1e600 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73  table(char **res
1e610 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ult);../*.** CAP
1e620 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64  I3REF: Formatted
1e630 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67   String Printing
1e640 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
1e650 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1e660 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20  are work-alikes 
1e670 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29  of the "printf()
1e680 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63  " family of func
1e690 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68  tions.** from th
1e6a0 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
1e6b0 72 61 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72  rary..** These r
1e6c0 6f 75 74 69 6e 65 73 20 75 6e 64 65 72 73 74 61  outines understa
1e6d0 6e 64 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 63  nd most of the c
1e6e0 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d 61 74  ommon K&R format
1e6f0 74 69 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a  ting options,.**
1e700 20 70 6c 75 73 20 73 6f 6d 65 20 61 64 64 69 74   plus some addit
1e710 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61  ional non-standa
1e720 72 64 20 66 6f 72 6d 61 74 73 2c 20 64 65 74 61  rd formats, deta
1e730 69 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e  iled below..** N
1e740 6f 74 65 20 74 68 61 74 20 73 6f 6d 65 20 6f 66  ote that some of
1e750 20 74 68 65 20 6d 6f 72 65 20 6f 62 73 63 75 72   the more obscur
1e760 65 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  e formatting opt
1e770 69 6f 6e 73 20 66 72 6f 6d 20 72 65 63 65 6e 74  ions from recent
1e780 0a 2a 2a 20 43 2d 6c 69 62 72 61 72 79 20 73 74  .** C-library st
1e790 61 6e 64 61 72 64 73 20 61 72 65 20 6f 6d 69 74  andards are omit
1e7a0 74 65 64 20 66 72 6f 6d 20 74 68 69 73 20 69 6d  ted from this im
1e7b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a  plementation..**
1e7c0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1e7d0 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73  _mprintf() and s
1e7e0 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
1e7f0 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65  ) routines write
1e800 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74   their.** result
1e810 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  s into memory ob
1e820 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
1e830 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a  ite3_malloc()]..
1e840 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72  ** The strings r
1e850 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
1e860 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68   two routines sh
1e870 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61  ould be.** relea
1e880 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
1e890 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20  free()].  ^Both 
1e8a0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1e8b0 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
1e8c0 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  r if [sqlite3_ma
1e8d0 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c  lloc()] is unabl
1e8e0 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e  e to allocate en
1e8f0 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74  ough.** memory t
1e900 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c  o hold the resul
1e910 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  ting string..**.
1e920 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
1e930 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _snprintf() rout
1e940 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ine is similar t
1e950 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66  o "snprintf()" f
1e960 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64  rom.** the stand
1e970 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20  ard C library.  
1e980 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72  The result is wr
1e990 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a  itten into the.*
1e9a0 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65  * buffer supplie
1e9b0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
1e9c0 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20  parameter whose 
1e9d0 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79  size is given by
1e9e0 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61  .** the first pa
1e9f0 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68  rameter. Note th
1ea00 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20  at the order of 
1ea10 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f  the.** first two
1ea20 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72   parameters is r
1ea30 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70  eversed from snp
1ea40 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73  rintf().)^  This
1ea50 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72   is an.** histor
1ea60 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68  ical accident th
1ea70 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78  at cannot be fix
1ea80 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ed without break
1ea90 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ing.** backwards
1eaa0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20   compatibility. 
1eab0 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61   ^(Note also tha
1eac0 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  t sqlite3_snprin
1ead0 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20  tf().** returns 
1eae0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73  a pointer to its
1eaf0 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20   buffer instead 
1eb00 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
1eb10 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61  .** characters a
1eb20 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20  ctually written 
1eb30 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e  into the buffer.
1eb40 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61  )^  We admit tha
1eb50 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  t.** the number 
1eb60 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72  of characters wr
1eb70 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61  itten would be a
1eb80 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74   more useful ret
1eb90 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74  urn.** value but
1eba0 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67   we cannot chang
1ebb0 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  e the implementa
1ebc0 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
1ebd0 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f  snprintf().** no
1ebe0 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  w without breaki
1ebf0 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ng compatibility
1ec00 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67  ..**.** ^As long
1ec10 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73   as the buffer s
1ec20 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74  ize is greater t
1ec30 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65  han zero, sqlite
1ec40 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
1ec50 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
1ec60 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c  the buffer is al
1ec70 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ways zero-termin
1ec80 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73  ated.  ^The firs
1ec90 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22  t.** parameter "
1eca0 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20  n" is the total 
1ecb0 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
1ecc0 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70  er, including sp
1ecd0 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a  ace for.** the z
1ece0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
1ecf0 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20   So the longest 
1ed00 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20  string that can 
1ed10 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a  be completely.**
1ed20 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65   written will be
1ed30 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e   n-1 characters.
1ed40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1ed50 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20  te3_vsnprintf() 
1ed60 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72  routine is a var
1ed70 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20  args version of 
1ed80 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1ed90 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ()..**.** These 
1eda0 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70  routines all imp
1edb0 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69  lement some addi
1edc0 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e  tional formattin
1edd0 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61  g.** options tha
1ede0 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72  t are useful for
1edf0 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51   constructing SQ
1ee00 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
1ee10 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61   All of the usua
1ee20 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61  l printf() forma
1ee30 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70  tting options ap
1ee40 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f  ply.  In additio
1ee50 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61  n, there.** is a
1ee60 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 22  re "%q", "%Q", "
1ee70 25 77 22 20 61 6e 64 20 22 25 7a 22 20 6f 70 74  %w" and "%z" opt
1ee80 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ions..**.** ^(Th
1ee90 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %q option work
1eea0 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61  s like %s in tha
1eeb0 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73  t it substitutes
1eec0 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65   a nul-terminate
1eed0 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d  d.** string from
1eee0 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69   the argument li
1eef0 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f  st.  But %q also
1ef00 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27   doubles every '
1ef10 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  \'' character..*
1ef20 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64  * %q is designed
1ef30 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20   for use inside 
1ef40 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
1ef50 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67  .)^  By doubling
1ef60 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68   each '\''.** ch
1ef70 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70  aracter it escap
1ef80 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65  es that characte
1ef90 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20  r and allows it 
1efa0 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69  to be inserted i
1efb0 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  nto.** the strin
1efc0 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61  g..**.** For exa
1efd0 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65  mple, assume the
1efe0 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65   string variable
1eff0 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20   zText contains 
1f000 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  text as follows:
1f010 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1f020 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
1f030 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73  r *zText = "It's
1f040 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a   a happy day!";.
1f050 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1f060 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65  quote>.**.** One
1f070 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65   can use this te
1f080 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  xt in an SQL sta
1f090 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77  tement as follow
1f0a0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1f0b0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
1f0c0 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
1f0d0 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
1f0e0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
1f0f0 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54  ALUES('%q')", zT
1f100 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
1f110 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
1f120 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
1f130 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
1f140 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1f150 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1f160 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66  Because the %q f
1f170 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20  ormat string is 
1f180 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63  used, the '\'' c
1f190 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78  haracter in zTex
1f1a0 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20  t.** is escaped 
1f1b0 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65  and the SQL gene
1f1c0 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c  rated is as foll
1f1d0 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1f1e0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1f1f0 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
1f200 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27  le1 VALUES('It''
1f210 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29  s a happy day!')
1f220 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1f230 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1f240 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20  is is correct.  
1f250 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69  Had we used %s i
1f260 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68  nstead of %q, th
1f270 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a  e generated SQL.
1f280 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f  ** would have lo
1f290 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a  oked like this:.
1f2a0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1f2b0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
1f2c0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
1f2d0 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61  ALUES('It's a ha
1f2e0 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c  ppy day!');.** <
1f2f0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1f300 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65  e>.**.** This se
1f310 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20  cond example is 
1f320 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72  an SQL syntax er
1f330 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72  ror.  As a gener
1f340 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75  al rule you shou
1f350 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  ld.** always use
1f360 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %q instead of %
1f370 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  s when inserting
1f380 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72   text into a str
1f390 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a  ing literal..**.
1f3a0 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69  ** ^(The %Q opti
1f3b0 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71  on works like %q
1f3c0 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20   except it also 
1f3d0 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74  adds single quot
1f3e0 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65  es around.** the
1f3f0 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
1f400 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41  total string.  A
1f410 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20  dditionally, if 
1f420 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e  the parameter in
1f430 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   the.** argument
1f440 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20   list is a NULL 
1f450 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73  pointer, %Q subs
1f460 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74  titutes the text
1f470 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74   "NULL" (without
1f480 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  .** single quote
1f490 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65  s).)^  So, for e
1f4a0 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c  xample, one coul
1f4b0 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  d say:.**.** <bl
1f4c0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1f4d0 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
1f4e0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1f4f0 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
1f500 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20  le VALUES(%Q)", 
1f510 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
1f520 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
1f530 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
1f540 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
1f550 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
1f560 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1f570 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65  * The code above
1f580 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63   will render a c
1f590 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65  orrect SQL state
1f5a0 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c  ment in the zSQL
1f5b0 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65  .** variable eve
1f5c0 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76  n if the zText v
1f5d0 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c  ariable is a NUL
1f5e0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
1f5f0 20 5e 28 54 68 65 20 22 25 77 22 20 66 6f 72 6d   ^(The "%w" form
1f600 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73  atting option is
1f610 20 6c 69 6b 65 20 22 25 71 22 20 65 78 63 65 70   like "%q" excep
1f620 74 20 74 68 61 74 20 69 74 20 65 78 70 65 63 74  t that it expect
1f630 73 20 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74 61  s to.** be conta
1f640 69 6e 65 64 20 77 69 74 68 69 6e 20 64 6f 75 62  ined within doub
1f650 6c 65 2d 71 75 6f 74 65 73 20 69 6e 73 74 65 61  le-quotes instea
1f660 64 20 6f 66 20 73 69 6e 67 6c 65 20 71 75 6f 74  d of single quot
1f670 65 73 2c 20 61 6e 64 20 69 74 0a 2a 2a 20 65 73  es, and it.** es
1f680 63 61 70 65 73 20 74 68 65 20 64 6f 75 62 6c 65  capes the double
1f690 2d 71 75 6f 74 65 20 63 68 61 72 61 63 74 65 72  -quote character
1f6a0 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
1f6b0 73 69 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20  single-quote.** 
1f6c0 63 68 61 72 61 63 74 65 72 2e 29 5e 20 20 54 68  character.)^  Th
1f6d0 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e  e "%w" formattin
1f6e0 67 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 74 65  g option is inte
1f6f0 6e 64 65 64 20 66 6f 72 20 73 61 66 65 6c 79 20  nded for safely 
1f700 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 61 62  inserting.** tab
1f710 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61  le and column na
1f720 6d 65 73 20 69 6e 74 6f 20 61 20 63 6f 6e 73 74  mes into a const
1f730 72 75 63 74 65 64 20 53 51 4c 20 73 74 61 74 65  ructed SQL state
1f740 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ment..**.** ^(Th
1f750 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e  e "%z" formattin
1f760 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  g option works l
1f770 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74  ike "%s" but wit
1f780 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f  h the.** additio
1f790 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65  n that after the
1f7a0 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e   string has been
1f7b0 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64   read and copied
1f7c0 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73   into.** the res
1f7d0 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ult, [sqlite3_fr
1f7e0 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  ee()] is called 
1f7f0 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  on the input str
1f800 69 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45  ing.)^.*/.SQLITE
1f810 5f 41 50 49 20 63 68 61 72 20 2a 53 51 4c 49 54  _API char *SQLIT
1f820 45 5f 43 44 45 43 4c 20 73 71 6c 69 74 65 33 5f  E_CDECL sqlite3_
1f830 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
1f840 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45  ar*,...);.SQLITE
1f850 5f 41 50 49 20 63 68 61 72 20 2a 53 51 4c 49 54  _API char *SQLIT
1f860 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
1f870 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  3_vmprintf(const
1f880 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
1f890 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61  ;.SQLITE_API cha
1f8a0 72 20 2a 53 51 4c 49 54 45 5f 43 44 45 43 4c 20  r *SQLITE_CDECL 
1f8b0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1f8c0 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74  (int,char*,const
1f8d0 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51   char*, ...);.SQ
1f8e0 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 53  LITE_API char *S
1f8f0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
1f900 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
1f910 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
1f920 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
1f930 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1f940 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
1f950 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a  ion Subsystem.**
1f960 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
1f970 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74  ore uses these t
1f980 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hree routines fo
1f990 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e  r all of its own
1f9a0 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d  .** internal mem
1f9b0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
1f9c0 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20  eeds. "Core" in 
1f9d0 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
1f9e0 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tence.** does no
1f9f0 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74  t include operat
1fa00 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
1fa10 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  fic VFS implemen
1fa20 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20  tation.  The.** 
1fa30 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73  Windows VFS uses
1fa40 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29   native malloc()
1fa50 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20   and free() for 
1fa60 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e  some operations.
1fa70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1fa80 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75  te3_malloc() rou
1fa90 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
1faa0 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63  ointer to a bloc
1fab0 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61  k.** of memory a
1fac0 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
1fad0 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65  in length, where
1fae0 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65   N is the parame
1faf0 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ter..** ^If sqli
1fb00 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
1fb10 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e  unable to obtain
1fb20 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65   sufficient free
1fb30 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72  .** memory, it r
1fb40 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
1fb50 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20  inter.  ^If the 
1fb60 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a  parameter N to.*
1fb70 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1fb80 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65  () is zero or ne
1fb90 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69  gative then sqli
1fba0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74  te3_malloc() ret
1fbb0 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  urns.** a NULL p
1fbc0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
1fbd0 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  he sqlite3_mallo
1fbe0 63 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77  c64(N) routine w
1fbf0 6f 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a  orks just like.*
1fc00 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1fc10 28 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20  (N) except that 
1fc20 4e 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64  N is an unsigned
1fc30 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
1fc40 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20  instead.** of a 
1fc50 73 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e  signed 32-bit in
1fc60 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  teger..**.** ^Ca
1fc70 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72  lling sqlite3_fr
1fc80 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ee() with a poin
1fc90 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72  ter previously r
1fca0 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
1fcb0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f  lite3_malloc() o
1fcc0 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
1fcd0 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61  c() releases tha
1fce0 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74  t memory so.** t
1fcf0 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20  hat it might be 
1fd00 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71  reused.  ^The sq
1fd10 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75  lite3_free() rou
1fd20 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d  tine is.** a no-
1fd30 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20  op if is called 
1fd40 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
1fd50 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20  ter.  Passing a 
1fd60 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
1fd70 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  to sqlite3_free(
1fd80 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20  ) is harmless.  
1fd90 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65  After being free
1fda0 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f  d, memory.** sho
1fdb0 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72  uld neither be r
1fdc0 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e  ead nor written.
1fdd0 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70    Even reading p
1fde0 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a  reviously freed.
1fdf0 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20  ** memory might 
1fe00 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d  result in a segm
1fe10 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f  entation fault o
1fe20 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
1fe30 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20  rror..** Memory 
1fe40 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65  corruption, a se
1fe50 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74  gmentation fault
1fe60 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  , or other sever
1fe70 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74  e error.** might
1fe80 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74   result if sqlit
1fe90 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c  e3_free() is cal
1fea0 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e  led with a non-N
1feb0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ULL pointer that
1fec0 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61  .** was not obta
1fed0 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
1fee0 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
1fef0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
1ff00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1ff10 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1ff20 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
1ff30 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a  pts to resize a.
1ff40 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20  ** prior memory 
1ff50 61 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20  allocation X to 
1ff60 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  be at least N by
1ff70 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
1ff80 58 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  X parameter to s
1ff90 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1ffa0 2c 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  ,N).** is a NULL
1ffb0 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74   pointer then it
1ffc0 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64  s behavior is id
1ffd0 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69  entical to calli
1ffe0 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ng.** sqlite3_ma
1fff0 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20  lloc(N)..** ^If 
20000 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20  the N parameter 
20010 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
20020 6f 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20  oc(X,N) is zero 
20030 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74  or.** negative t
20040 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
20050 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20   is exactly the 
20060 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a  same as calling.
20070 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ** sqlite3_free(
20080 58 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f  X)..** ^sqlite3_
20090 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74  realloc(X,N) ret
200a0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
200b0 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  o a memory alloc
200c0 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c  ation.** of at l
200d0 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
200e0 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20  size or NULL if 
200f0 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d  insufficient mem
20100 6f 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65  ory is available
20110 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68  ..** ^If M is th
20120 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72  e size of the pr
20130 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ior allocation, 
20140 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79  then min(N,M) by
20150 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72  tes.** of the pr
20160 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61  ior allocation a
20170 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74  re copied into t
20180 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
20190 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a  buffer returned.
201a0 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65  ** by sqlite3_re
201b0 61 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74  alloc(X,N) and t
201c0 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
201d0 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a  ion is freed..**
201e0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61   ^If sqlite3_rea
201f0 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e  lloc(X,N) return
20200 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20  s NULL and N is 
20210 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74  positive, then t
20220 68 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f  he.** prior allo
20230 63 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72  cation is not fr
20240 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
20250 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36  sqlite3_realloc6
20260 34 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  4(X,N) interface
20270 73 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65  s works the same
20280 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   as.** sqlite3_r
20290 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65  ealloc(X,N) exce
202a0 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 20 36  pt that N is a 6
202b0 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69  4-bit unsigned i
202c0 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a  nteger instead.*
202d0 2a 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69  * of a 32-bit si
202e0 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  gned integer..**
202f0 0a 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d  .** ^If X is a m
20300 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
20310 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61   previously obta
20320 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
20330 33 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73  3_malloc(),.** s
20340 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28  qlite3_malloc64(
20350 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  ), sqlite3_reall
20360 6f 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  oc(), or sqlite3
20370 5f 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68  _realloc64(), th
20380 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73  en.** sqlite3_ms
20390 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 74  ize(X) returns t
203a0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20  he size of that 
203b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
203c0 6e 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  n in bytes..** ^
203d0 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
203e0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73  ed by sqlite3_ms
203f0 69 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65 20  ize(X) might be 
20400 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20  larger than the 
20410 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74  number.** of byt
20420 65 73 20 72 65 71 75 65 73 74 65 64 20 77 68 65  es requested whe
20430 6e 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65  n X was allocate
20440 64 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e  d.  ^If X is a N
20450 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
20460 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a  .** sqlite3_msiz
20470 65 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72  e(X) returns zer
20480 6f 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20  o.  If X points 
20490 74 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61  to something tha
204a0 74 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20  t is not.** the 
204b0 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d  beginning of mem
204c0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ory allocation, 
204d0 6f 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20  or if it points 
204e0 74 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a  to a formerly.**
204f0 20 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c   valid memory al
20500 6c 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61  location that ha
20510 73 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64  s now been freed
20520 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
20530 69 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  ior.** of sqlite
20540 33 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e  3_msize(X) is un
20550 64 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73  defined and poss
20560 69 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a  ibly harmful..**
20570 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
20580 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
20590 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71  te3_malloc(), sq
205a0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c  lite3_realloc(),
205b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
205c0 6f 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69  oc64(), and sqli
205d0 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a  te3_realloc64().
205e0 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69  ** is always ali
205f0 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74  gned to at least
20600 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64   an 8 byte bound
20610 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20  ary, or to a.** 
20620 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20  4 byte boundary 
20630 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34  if the [SQLITE_4
20640 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41  _BYTE_ALIGNED_MA
20650 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  LLOC] compile-ti
20660 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20  me.** option is 
20670 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53  used..**.** In S
20680 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
20690 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69  5.0 and 3.5.1, i
206a0 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74  t was possible t
206b0 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20  o define.** the 
206c0 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f  SQLITE_OMIT_MEMO
206d0 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68  RY_ALLOCATION wh
206e0 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20  ich would cause 
206f0 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20  the built-in.** 
20700 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
20710 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
20720 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20   to be omitted. 
20730 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79   That capability
20740 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  .** is no longer
20750 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79   provided.  Only
20760 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
20770 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20   allocators can 
20780 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50  be used..**.** P
20790 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76  rior to SQLite v
207a0 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74  ersion 3.7.10, t
207b0 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e  he Windows OS in
207c0 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61  terface layer ca
207d0 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74  lled.** the syst
207e0 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  em malloc() and 
207f0 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20  free() directly 
20800 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a  when converting.
20810 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74  ** filenames bet
20820 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65  ween the UTF-8 e
20830 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20  ncoding used by 
20840 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68  SQLite.** and wh
20850 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20  atever filename 
20860 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
20870 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c   by the particul
20880 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e  ar Windows.** in
20890 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d  stallation.  Mem
208a0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
208b0 72 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63  rrors were detec
208c0 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79  ted, but.** they
208d0 20 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62   were reported b
208e0 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43  ack as [SQLITE_C
208f0 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b  ANTOPEN] or.** [
20900 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61  SQLITE_IOERR] ra
20910 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
20920 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
20930 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  The pointer argu
20940 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65  ments to [sqlite
20950 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73  3_free()] and [s
20960 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
20970 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74  ].** must be eit
20980 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65  her NULL or else
20990 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e   pointers obtain
209a0 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a  ed from a prior.
209b0 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ** invocation of
209c0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
209d0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
209e0 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20  realloc()] that 
209f0 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20  have.** not yet 
20a00 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a  been released..*
20a10 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
20a20 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65  tion must not re
20a30 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20  ad or write any 
20a40 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f  part of.** a blo
20a50 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74  ck of memory aft
20a60 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72  er it has been r
20a70 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a  eleased using.**
20a80 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
20a90 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
20aa0 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  alloc()]..*/.SQL
20ab0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51  ITE_API void *SQ
20ac0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
20ad0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29  ite3_malloc(int)
20ae0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
20af0 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  d *SQLITE_STDCAL
20b00 4c 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  L sqlite3_malloc
20b10 36 34 28 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  64(sqlite3_uint6
20b20 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  4);.SQLITE_API v
20b30 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  oid *SQLITE_STDC
20b40 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  ALL sqlite3_real
20b50 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  loc(void*, int);
20b60 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
20b70 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
20b80 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
20b90 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65  64(void*, sqlite
20ba0 33 5f 75 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54  3_uint64);.SQLIT
20bb0 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54  E_API void SQLIT
20bc0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
20bd0 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 53  3_free(void*);.S
20be0 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
20bf0 33 5f 75 69 6e 74 36 34 20 53 51 4c 49 54 45 5f  3_uint64 SQLITE_
20c00 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
20c10 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f  msize(void*);../
20c20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
20c30 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20  emory Allocator 
20c40 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a  Statistics.**.**
20c50 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73   SQLite provides
20c60 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72   these two inter
20c70 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74  faces for report
20c80 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75  ing on the statu
20c90 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  s.** of the [sql
20ca0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20  ite3_malloc()], 
20cb0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
20cc0 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  , and [sqlite3_r
20cd0 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75  ealloc()].** rou
20ce0 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72  tines, which for
20cf0 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d  m the built-in m
20d00 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
20d10 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a   subsystem..**.*
20d20 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
20d30 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72  memory_used()] r
20d40 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
20d50 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
20d60 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20  es.** of memory 
20d70 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61  currently outsta
20d80 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20  nding (malloced 
20d90 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a  but not freed)..
20da0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
20db0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
20dc0 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  r()] routine ret
20dd0 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  urns the maximum
20de0 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71  .** value of [sq
20df0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
20e00 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68  d()] since the h
20e10 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
20e20 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74  * was last reset
20e30 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72  .  ^The values r
20e40 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
20e50 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
20e60 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
20e70 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
20e80 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61  ter()] include a
20e90 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61  ny overhead.** a
20ea0 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69  dded by SQLite i
20eb0 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61  n its implementa
20ec0 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
20ed0 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62  _malloc()],.** b
20ee0 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20  ut not overhead 
20ef0 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79  added by the any
20f00 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74   underlying syst
20f10 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f  em library.** ro
20f20 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c  utines that [sql
20f30 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d  ite3_malloc()] m
20f40 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  ay call..**.** ^
20f50 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d  The memory high-
20f60 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65  water mark is re
20f70 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65  set to the curre
20f80 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b  nt value of.** [
20f90 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
20fa0 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e  sed()] if and on
20fb0 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ly if the parame
20fc0 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
20fd0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
20fe0 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20  ter()] is true. 
20ff0 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75   ^The value retu
21000 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  rned.** by [sqli
21010 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
21020 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20  ater(1)] is the 
21030 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
21040 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ** prior to the 
21050 72 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45  reset..*/.SQLITE
21060 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74  _API sqlite3_int
21070 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  64 SQLITE_STDCAL
21080 4c 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  L sqlite3_memory
21090 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 53 51 4c  _used(void);.SQL
210a0 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
210b0 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 54 44  int64 SQLITE_STD
210c0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 65 6d  CALL sqlite3_mem
210d0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e  ory_highwater(in
210e0 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f  t resetFlag);../
210f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50  *.** CAPI3REF: P
21100 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d  seudo-Random Num
21110 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a  ber Generator.**
21120 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61  .** SQLite conta
21130 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69  ins a high-quali
21140 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  ty pseudo-random
21150 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f   number generato
21160 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f  r (PRNG) used to
21170 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f  .** select rando
21180 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44  m [ROWID | ROWID
21190 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  s] when insertin
211a0 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e  g new records in
211b0 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a  to a table that.
211c0 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20  ** already uses 
211d0 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73  the largest poss
211e0 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54  ible [ROWID].  T
211f0 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20  he PRNG is also 
21200 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  used for.** the 
21210 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28  build-in random(
21220 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62  ) and randomblob
21230 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  () SQL functions
21240 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  .  This interfac
21250 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c  e allows.** appl
21260 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65  ications to acce
21270 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47  ss the same PRNG
21280 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f   for other purpo
21290 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61  ses..**.** ^A ca
212a0 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  ll to this routi
212b0 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65  ne stores N byte
212c0 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
212d0 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a  into buffer P..*
212e0 2a 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74  * ^The P paramet
212f0 65 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c  er can be a NULL
21300 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
21310 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ^If this routine
21320 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72   has not been pr
21330 65 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20  eviously called 
21340 6f 72 20 69 66 20 74 68 65 20 70 72 65 76 69 6f  or if the previo
21350 75 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e  us.** call had N
21360 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f   less than one o
21370 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
21380 20 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65   for P, then the
21390 20 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64   PRNG is.** seed
213a0 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e  ed using randomn
213b0 65 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ess obtained fro
213c0 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  m the xRandomnes
213d0 73 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74  s method of.** t
213e0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
213f0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
21400 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76  .** ^If the prev
21410 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69  ious call to thi
21420 73 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e  s routine had an
21430 20 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20   N of 1 or more 
21440 61 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c  and a.** non-NUL
21450 4c 20 50 20 74 68 65 6e 20 74 68 65 20 70 73 65  L P then the pse
21460 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69  udo-randomness i
21470 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69  s generated.** i
21480 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69  nternally and wi
21490 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74  thout recourse t
214a0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  o the [sqlite3_v
214b0 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a  fs] xRandomness.
214c0 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51  ** method..*/.SQ
214d0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51  LITE_API void SQ
214e0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
214f0 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28  ite3_randomness(
21500 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b  int N, void *P);
21510 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
21520 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41  : Compile-Time A
21530 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c  uthorization Cal
21540 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44  lbacks.** METHOD
21550 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
21560 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
21570 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f  gisters an autho
21580 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77  rizer callback w
21590 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
215a0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
215b0 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c  nnection], suppl
215c0 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74  ied in the first
215d0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
215e0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
215f0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
21600 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65  d as SQL stateme
21610 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f  nts are being co
21620 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71  mpiled.** by [sq
21630 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
21640 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
21650 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
21660 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  e_v2()],.** [sql
21670 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
21680 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
21690 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20  repare16_v2()]. 
216a0 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20   ^At various.** 
216b0 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68  points during th
216c0 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72  e compilation pr
216d0 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20  ocess, as logic 
216e0 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  is being created
216f0 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76  .** to perform v
21700 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20  arious actions, 
21710 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
21720 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
21730 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20  ed to.** see if 
21740 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72  those actions ar
21750 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65  e allowed.  ^The
21760 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
21770 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  back should.** r
21780 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
21790 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61  ] to allow the a
217a0 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49  ction, [SQLITE_I
217b0 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c  GNORE] to disall
217c0 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  ow the.** specif
217d0 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c  ic action but al
217e0 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74  low the SQL stat
217f0 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75  ement to continu
21800 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69  e to be.** compi
21810 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  led, or [SQLITE_
21820 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74  DENY] to cause t
21830 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74  he entire SQL st
21840 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a  atement to be.**
21850 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61   rejected with a
21860 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68  n error.  ^If th
21870 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
21880 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
21890 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72   any value other
218a0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47   than [SQLITE_IG
218b0 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  NORE], [SQLITE_O
218c0 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  K], or [SQLITE_D
218d0 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ENY].** then the
218e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
218f0 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
21900 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
21910 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65  triggered.** the
21920 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
21930 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
21940 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a  ror message..**.
21950 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** When the call
21960 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
21970 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d  LITE_OK], that m
21980 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69  eans the operati
21990 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  on.** requested 
219a0 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68  is ok.  ^When th
219b0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
219c0 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  ns [SQLITE_DENY]
219d0 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  , the.** [sqlite
219e0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
219f0 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
21a00 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
21a10 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  d the.** authori
21a20 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
21a30 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
21a40 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74  age explaining t
21a50 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73  hat.** access is
21a60 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20   denied. .**.** 
21a70 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
21a80 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
21a90 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
21aa0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
21ab0 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
21ac0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
21ad0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
21ae0 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e  r() interface. ^
21af0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
21b00 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63  eter.** to the c
21b10 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
21b20 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f  teger [SQLITE_CO
21b30 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65  PY | action code
21b40 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  ] that specifies
21b50 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c  .** the particul
21b60 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  ar action to be 
21b70 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65  authorized. ^The
21b80 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73   third through s
21b90 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a  ixth parameters.
21ba0 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
21bb0 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d  ck are zero-term
21bc0 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
21bd0 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69  hat contain addi
21be0 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c  tional.** detail
21bf0 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69  s about the acti
21c00 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
21c10 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  zed..**.** ^If t
21c20 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69  he action code i
21c30 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a  s [SQLITE_READ].
21c40 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62  ** and the callb
21c50 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
21c60 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
21c70 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
21c80 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61  d statement] sta
21c90 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72  tement is constr
21ca0 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74  ucted to substit
21cb0 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61  ute.** a NULL va
21cc0 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  lue in place of 
21cd0 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
21ce0 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65   that would have
21cf0 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66  .** been read if
21d00 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64   [SQLITE_OK] had
21d10 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20   been returned. 
21d20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e   The [SQLITE_IGN
21d30 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63  ORE].** return c
21d40 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65  an be used to de
21d50 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  ny an untrusted 
21d60 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69  user access to i
21d70 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c  ndividual.** col
21d80 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e  umns of a table.
21d90 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69  .** ^If the acti
21da0 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
21db0 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74  TE_DELETE] and t
21dc0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
21dd0 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  rns.** [SQLITE_I
21de0 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20  GNORE] then the 
21df0 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69  [DELETE] operati
21e00 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20  on proceeds but 
21e10 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65  the.** [truncate
21e20 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69   optimization] i
21e30 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61  s disabled and a
21e40 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  ll rows are dele
21e50 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79  ted individually
21e60 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f  ..**.** An autho
21e70 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68  rizer is used wh
21e80 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
21e90 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d  are | preparing]
21ea0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
21eb0 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75  ts from an untru
21ec0 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20  sted source, to 
21ed0 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  ensure that the 
21ee0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
21ef0 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20  * do not try to 
21f00 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79  access data they
21f10 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64   are not allowed
21f20 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74   to see, or that
21f30 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
21f40 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d  try to execute m
21f50 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65  alicious stateme
21f60 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20  nts that damage 
21f70 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46  the database.  F
21f80 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61  or.** example, a
21f90 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61  n application ma
21fa0 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74  y allow a user t
21fb0 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72  o enter arbitrar
21fc0 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73  y.** SQL queries
21fd0 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20   for evaluation 
21fe0 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20  by a database.  
21ff0 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  But the applicat
22000 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ion does.** not 
22010 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f  want the user to
22020 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65   be able to make
22030 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67   arbitrary chang
22040 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  es to the.** dat
22050 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f  abase.  An autho
22060 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e  rizer could then
22070 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65   be put in place
22080 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73   while the.** us
22090 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69  er-entered SQL i
220a0 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33  s being [sqlite3
220b0 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
220c0 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73  red] that.** dis
220d0 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e  allows everythin
220e0 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54  g except [SELECT
220f0 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
22100 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
22110 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72   that need to pr
22120 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75  ocess SQL from u
22130 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73  ntrusted sources
22140 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63  .** might also c
22150 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67  onsider lowering
22160 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73   resource limits
22170 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
22180 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20  limit()].** and 
22190 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73  limiting databas
221a0 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65  e size using the
221b0 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
221c0 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e  ] [PRAGMA].** in
221d0 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69   addition to usi
221e0 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  ng an authorizer
221f0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61  ..**.** ^(Only a
22200 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a   single authoriz
22210 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61  er can be in pla
22220 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65  ce on a database
22230 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61   connection.** a
22240 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20  t a time.  Each 
22250 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
22260 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f  set_authorizer o
22270 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20  verrides the.** 
22280 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e  previous call.)^
22290 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61    ^Disable the a
222a0 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73  uthorizer by ins
222b0 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63  talling a NULL c
222c0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20  allback..** The 
222d0 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69  authorizer is di
222e0 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
222f0 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74  t..**.** The aut
22300 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
22310 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
22320 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
22330 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
22340 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
22350 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
22360 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
22370 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20  llback..** Note 
22380 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
22390 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
223a0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
223b0 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
223c0 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
223d0 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
223e0 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
223f0 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
22400 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
22410 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70  ^When [sqlite3_p
22420 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20  repare_v2()] is 
22430 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20  used to prepare 
22440 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65  a statement, the
22450 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69  .** statement mi
22460 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72  ght be re-prepar
22470 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74  ed during [sqlit
22480 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74  e3_step()] due t
22490 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63  o a .** schema c
224a0 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74  hange.  Hence, t
224b0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
224c0 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61  hould ensure tha
224d0 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74  t the.** correct
224e0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
224f0 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20  back remains in 
22500 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65  place during the
22510 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
22520 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74  ]..**.** ^Note t
22530 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a  hat the authoriz
22540 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
22550 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69  nvoked only duri
22560 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ng.** [sqlite3_p
22570 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
22580 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68   variants.  Auth
22590 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74  orization is not
225a0 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75  .** performed du
225b0 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65  ring statement e
225c0 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71  valuation in [sq
225d0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75  lite3_step()], u
225e0 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74  nless.** as stat
225f0 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  ed in the previo
22600 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71  us paragraph, sq
22610 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76  lite3_step() inv
22620 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  okes.** sqlite3_
22630 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20  prepare_v2() to 
22640 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74  reprepare a stat
22650 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63  ement after a sc
22660 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a  hema change..*/.
22670 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
22680 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
22690 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
226a0 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a  izer(.  sqlite3*
226b0 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29  ,.  int (*xAuth)
226c0 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
226d0 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
226e0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
226f0 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76  onst char*),.  v
22700 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29  oid *pUserData.)
22710 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
22720 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65  F: Authorizer Re
22730 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  turn Codes.**.**
22740 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
22750 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
22760 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
22770 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73  ck function] mus
22780 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68  t.** return eith
22790 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  er [SQLITE_OK] o
227a0 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74  r one of these t
227b0 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20  wo constants in 
227c0 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e  order.** to sign
227d0 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65  al SQLite whethe
227e0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74  r or not the act
227f0 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
22800 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73  .  See the.** [s
22810 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
22820 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
22830 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  er documentation
22840 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  ] for additional
22850 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
22860 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
22870 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69   SQLITE_IGNORE i
22880 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61  s also used as a
22890 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c   [conflict resol
228a0 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72  ution mode].** r
228b0 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68 65  eturned from the
228c0 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f   [sqlite3_vtab_o
228d0 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e  n_conflict()] in
228e0 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66  terface..*/.#def
228f0 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20  ine SQLITE_DENY 
22900 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74    1   /* Abort t
22910 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
22920 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a   with an error *
22930 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22940 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44  _IGNORE 2   /* D
22950 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73  on't allow acces
22960 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e  s, but don't gen
22970 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a  erate an error *
22980 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
22990 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63  F: Authorizer Ac
229a0 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  tion Codes.**.**
229b0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
229c0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20  t_authorizer()] 
229d0 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
229e0 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ers a callback f
229f0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  unction.** that 
22a00 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75  is invoked to au
22a10 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20  thorize certain 
22a20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63  SQL statement ac
22a30 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73  tions.  The.** s
22a40 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
22a50 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
22a60 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  is an integer co
22a70 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65  de that specifie
22a80 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e  s.** what action
22a90 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72   is being author
22aa0 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65  ized.  These are
22ab0 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74   the integer act
22ac0 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a  ion codes that.*
22ad0 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
22ae0 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65   callback may be
22af0 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   passed..**.** T
22b00 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65  hese action code
22b10 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20   values signify 
22b20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65  what kind of ope
22b30 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a  ration is to be.
22b40 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ** authorized.  
22b50 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20  The 3rd and 4th 
22b60 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
22b70 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a  e authorization.
22b80 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
22b90 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72  tion will be par
22ba0 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20  ameters or NULL 
22bb0 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69  depending on whi
22bc0 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63  ch of these.** c
22bd0 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20  odes is used as 
22be0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
22bf0 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68  eter.  ^(The 5th
22c00 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
22c10 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
22c20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
22c30 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
22c40 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74  base ("main", "t
22c50 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69  emp",.** etc.) i
22c60 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20  f applicable.)^ 
22c70 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65   ^The 6th parame
22c80 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
22c90 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  rizer callback.*
22ca0 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  * is the name of
22cb0 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20   the inner-most 
22cc0 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20  trigger or view 
22cd0 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69  that is responsi
22ce0 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ble for.** the a
22cf0 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72  ccess attempt or
22d00 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63   NULL if this ac
22d10 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20  cess attempt is 
22d20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a  directly from.**
22d30 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63   top-level SQL c
22d40 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a  ode..*/./*******
22d50 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22d60 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22d70 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a  **** 3rd *******
22d80 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a  ***** 4th ******
22d90 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  *****/.#define S
22da0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44  QLITE_CREATE_IND
22db0 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20  EX          1   
22dc0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
22dd0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
22de0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22df0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c  LITE_CREATE_TABL
22e00 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f  E          2   /
22e10 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
22e20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22e30 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22e40 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
22e50 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a  INDEX     3   /*
22e60 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
22e70 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22e80 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22e90 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
22ea0 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20  ABLE     4   /* 
22eb0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
22ec0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
22ed0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22ee0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52  E_CREATE_TEMP_TR
22ef0 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54  IGGER   5   /* T
22f00 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
22f10 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
22f20 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22f30 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45  _CREATE_TEMP_VIE
22f40 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69  W      6   /* Vi
22f50 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
22f60 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
22f70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22f80 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20  CREATE_TRIGGER  
22f90 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69        7   /* Tri
22fa0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
22fb0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
22fc0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
22fd0 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20  REATE_VIEW      
22fe0 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77       8   /* View
22ff0 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
23000 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
23010 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
23020 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
23030 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65      9   /* Table
23040 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
23050 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
23060 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
23070 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  P_INDEX         
23080 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20    10   /* Index 
23090 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
230a0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
230b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
230c0 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
230d0 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   11   /* Table N
230e0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
230f0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
23100 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
23110 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20  TEMP_INDEX      
23120 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  12   /* Index Na
23130 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
23140 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
23150 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
23160 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31  EMP_TABLE      1
23170 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
23180 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
23190 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
231a0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
231b0 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34  MP_TRIGGER    14
231c0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
231d0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
231e0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
231f0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
23200 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20  P_VIEW       15 
23210 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
23220 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
23230 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
23240 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47  SQLITE_DROP_TRIG
23250 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20  GER         16  
23260 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
23270 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
23280 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
23290 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20  QLITE_DROP_VIEW 
232a0 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20             17   
232b0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
232c0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
232d0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
232e0 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20  LITE_INSERT     
232f0 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f            18   /
23300 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
23310 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
23320 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
23330 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20  ITE_PRAGMA      
23340 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a           19   /*
23350 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20   Pragma Name    
23360 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c   1st arg or NULL
23370 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
23380 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20  TE_READ         
23390 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20          20   /* 
233a0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
233b0 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
233c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
233d0 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  E_SELECT        
233e0 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e         21   /* N
233f0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e  ULL            N
23400 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
23410 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
23420 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20  _TRANSACTION    
23430 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70        22   /* Op
23440 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55  eration       NU
23450 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
23460 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23470 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20  UPDATE          
23480 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62       23   /* Tab
23490 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
234a0 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
234b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
234c0 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  TTACH           
234d0 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65      24   /* File
234e0 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c  name        NULL
234f0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
23500 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
23510 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
23520 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62     25   /* Datab
23530 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20  ase Name   NULL 
23540 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
23550 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54  efine SQLITE_ALT
23560 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  ER_TABLE        
23570 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61    26   /* Databa
23580 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20  se Name   Table 
23590 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
235a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e  fine SQLITE_REIN
235b0 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20  DEX             
235c0 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   27   /* Index N
235d0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
235e0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
235f0 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59  ine SQLITE_ANALY
23600 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
23610 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  28   /* Table Na
23620 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
23630 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
23640 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
23650 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32  _VTABLE        2
23660 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
23670 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
23680 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
23690 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54  e SQLITE_DROP_VT
236a0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30  ABLE          30
236b0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
236c0 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
236d0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
236e0 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e   SQLITE_FUNCTION
236f0 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20               31 
23700 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
23710 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61       Function Na
23720 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  me   */.#define 
23730 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54  SQLITE_SAVEPOINT
23740 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20              32  
23750 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
23760 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61      Savepoint Na
23770 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  me  */.#define S
23780 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20  QLITE_COPY      
23790 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20              0   
237a0 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65  /* No longer use
237b0 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
237c0 49 54 45 5f 52 45 43 55 52 53 49 56 45 20 20 20  ITE_RECURSIVE   
237d0 20 20 20 20 20 20 20 20 20 33 33 20 20 20 2f 2a           33   /*
237e0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
237f0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
23800 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
23810 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64  REF: Tracing And
23820 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74   Profiling Funct
23830 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ions.** METHOD: 
23840 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68  sqlite3.**.** Th
23850 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67  ese routines reg
23860 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  ister callback f
23870 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61  unctions that ca
23880 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a  n be used for.**
23890 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f   tracing and pro
238a0 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75  filing the execu
238b0 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74  tion of SQL stat
238c0 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ements..**.** ^T
238d0 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
238e0 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
238f0 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  by sqlite3_trace
23900 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74  () is invoked at
23910 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65  .** various time
23920 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74  s when an SQL st
23930 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67  atement is being
23940 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33   run by [sqlite3
23950 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68  _step()]..** ^Th
23960 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  e sqlite3_trace(
23970 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  ) callback is in
23980 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46  voked with a UTF
23990 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  -8 rendering of 
239a0 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  the.** SQL state
239b0 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65  ment text as the
239c0 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74   statement first
239d0 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e   begins executin
239e0 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e  g..** ^(Addition
239f0 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  al sqlite3_trace
23a00 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67  () callbacks mig
23a10 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65  ht occur.** as e
23a20 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75  ach triggered su
23a30 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65  bprogram is ente
23a40 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61  red.  The callba
23a50 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73  cks for triggers
23a60 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54  .** contain a UT
23a70 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20  F-8 SQL comment 
23a80 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20  that identifies 
23a90 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a  the trigger.)^.*
23aa0 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
23ab0 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49  _TRACE_SIZE_LIMI
23ac0 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  T] compile-time 
23ad0 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
23ae0 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74  ed to limit.** t
23af0 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f  he length of [bo
23b00 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65  und parameter] e
23b10 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20  xpansion in the 
23b20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65  output of sqlite
23b30 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a  3_trace()..**.**
23b40 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
23b50 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
23b60 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72  ed by sqlite3_pr
23b70 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b  ofile() is invok
23b80 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51  ed.** as each SQ
23b90 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  L statement fini
23ba0 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66  shes.  ^The prof
23bb0 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e  ile callback con
23bc0 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69  tains.** the ori
23bd0 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20  ginal statement 
23be0 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69  text and an esti
23bf0 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f  mate of wall-clo
23c00 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f  ck time.** of ho
23c10 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74  w long that stat
23c20 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75  ement took to ru
23c30 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65  n.  ^The profile
23c40 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d   callback.** tim
23c50 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66  e is in units of
23c60 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f   nanoseconds, ho
23c70 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e  wever the curren
23c80 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
23c90 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61  .** is only capa
23ca0 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ble of milliseco
23cb0 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f  nd resolution so
23cc0 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73   the six least s
23cd0 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69  ignificant.** di
23ce0 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65  gits in the time
23cf0 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73   are meaningless
23d00 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
23d10 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  ns of SQLite.** 
23d20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72  might provide gr
23d30 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e  eater resolution
23d40 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72   on the profiler
23d50 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a   callback.  The.
23d60 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  ** sqlite3_profi
23d70 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  le() function is
23d80 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65   considered expe
23d90 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a  rimental and is.
23da0 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  ** subject to ch
23db0 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76  ange in future v
23dc0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
23dd0 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
23de0 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54   void *SQLITE_ST
23df0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74 72  DCALL sqlite3_tr
23e00 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ace(sqlite3*, vo
23e10 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64  id(*xTrace)(void
23e20 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  *,const char*), 
23e30 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  void*);.SQLITE_A
23e40 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49  PI SQLITE_EXPERI
23e50 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 53 51 4c  MENTAL void *SQL
23e60 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
23e70 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69  te3_profile(sqli
23e80 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78  te3*,.   void(*x
23e90 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63  Profile)(void*,c
23ea0 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74  onst char*,sqlit
23eb0 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64  e3_uint64), void
23ec0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
23ed0 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72  REF: Query Progr
23ee0 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ess Callbacks.**
23ef0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
23f00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
23f10 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
23f20 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e  dler(D,N,X,P) in
23f30 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74  terface causes t
23f40 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  he callback.** f
23f50 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20  unction X to be 
23f60 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63  invoked periodic
23f70 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67  ally during long
23f80 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74   running calls t
23f90 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  o.** [sqlite3_ex
23fa0 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ec()], [sqlite3_
23fb0 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c  step()] and [sql
23fc0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
23fd0 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73  ] for.** databas
23fe0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20  e connection D. 
23ff0 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20   An example use 
24000 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65  for this.** inte
24010 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70  rface is to keep
24020 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64   a GUI updated d
24030 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75  uring a large qu
24040 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ery..**.** ^The 
24050 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70  parameter P is p
24060 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
24070 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
24080 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63  ter to the .** c
24090 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
240a0 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65   X.  ^The parame
240b0 74 65 72 20 4e 20 69 73 20 74 68 65 20 61 70 70  ter N is the app
240c0 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20  roximate number 
240d0 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20  of .** [virtual 
240e0 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74  machine instruct
240f0 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65  ions] that are e
24100 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e  valuated between
24110 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69   successive.** i
24120 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
24130 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e  e callback X.  ^
24140 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61  If N is less tha
24150 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70  n one then the p
24160 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c  rogress.** handl
24170 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a  er is disabled..
24180 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69  **.** ^Only a si
24190 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61  ngle progress ha
241a0 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66  ndler may be def
241b0 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65  ined at one time
241c0 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73   per.** [databas
241d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73  e connection]; s
241e0 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f  etting a new pro
241f0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
24200 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64  ncels the.** old
24210 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20   one.  ^Setting 
24220 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e  parameter X to N
24230 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65  ULL disables the
24240 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
24250 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72  r..** ^The progr
24260 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61  ess handler is a
24270 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20  lso disabled by 
24280 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76  setting N to a v
24290 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61  alue less.** tha
242a0 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  n 1..**.** ^If t
242b0 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
242c0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
242d0 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61  -zero, the opera
242e0 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72  tion is.** inter
242f0 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65  rupted.  This fe
24300 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65  ature can be use
24310 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
24320 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74  .** "Cancel" but
24330 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f  ton on a GUI pro
24340 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78  gress dialog box
24350 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67  ..**.** The prog
24360 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c  ress handler cal
24370 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
24380 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
24390 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
243a0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
243b0 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
243c0 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73  ked the progress
243d0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74   handler..** Not
243e0 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
243f0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
24400 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
24410 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
24420 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
24430 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
24440 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
24450 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
24460 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
24470 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
24480 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  d SQLITE_STDCALL
24490 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
244a0 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  s_handler(sqlite
244b0 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28  3*, int, int(*)(
244c0 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  void*), void*);.
244d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
244e0 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44   Opening A New D
244f0 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
24500 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f  on.** CONSTRUCTO
24510 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  R: sqlite3.**.**
24520 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
24530 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20   open an SQLite 
24540 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73  database file as
24550 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
24560 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61  e .** filename a
24570 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69  rgument. ^The fi
24580 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20  lename argument 
24590 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
245a0 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73  s UTF-8 for.** s
245b0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
245c0 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
245d0 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31  2() and as UTF-1
245e0 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
245f0 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f  byte.** order fo
24600 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  r sqlite3_open16
24610 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73  (). ^(A [databas
24620 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
24630 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a  ndle is usually.
24640 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a  ** returned in *
24650 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e  ppDb, even if an
24660 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20   error occurs.  
24670 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69  The only excepti
24680 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66  on is that.** if
24690 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c   SQLite is unabl
246a0 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65  e to allocate me
246b0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
246c0 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
246d0 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c  t,.** a NULL wil
246e0 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74  l be written int
246f0 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20  o *ppDb instead 
24700 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  of a pointer to 
24710 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a  the [sqlite3].**
24720 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20   object.)^ ^(If 
24730 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
24740 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63  opened (and/or c
24750 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66  reated) successf
24760 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53  ully, then.** [S
24770 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74  QLITE_OK] is ret
24780 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73  urned.  Otherwis
24790 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
247a0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  ] is returned.)^
247b0 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65   ^The.** [sqlite
247c0 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b  3_errmsg()] or [
247d0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
247e0 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e  ()] routines can
247f0 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
24800 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68  in.** an English
24810 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69   language descri
24820 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72  ption of the err
24830 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66  or following a f
24840 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a  ailure of any.**
24850 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
24860 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e  open() routines.
24870 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  .**.** ^The defa
24880 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c  ult encoding wil
24890 6c 20 62 65 20 55 54 46 2d 38 20 66 6f 72 20 64  l be UTF-8 for d
248a0 61 74 61 62 61 73 65 73 20 63 72 65 61 74 65 64  atabases created
248b0 20 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65   using.** sqlite
248c0 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
248d0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20  te3_open_v2().  
248e0 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63  ^The default enc
248f0 6f 64 69 6e 67 20 66 6f 72 20 64 61 74 61 62 61  oding for databa
24900 73 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 75  ses.** created u
24910 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65  sing sqlite3_ope
24920 6e 31 36 28 29 20 77 69 6c 6c 20 62 65 20 55 54  n16() will be UT
24930 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
24940 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
24950 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20  *.** Whether or 
24960 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  not an error occ
24970 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f  urs when it is o
24980 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73  pened, resources
24990 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
249a0 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
249b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
249c0 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72  ndle should be r
249d0 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61  eleased by.** pa
249e0 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
249f0 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68  ite3_close()] wh
24a00 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67  en it is no long
24a10 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  er required..**.
24a20 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  ** The sqlite3_o
24a30 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61  pen_v2() interfa
24a40 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  ce works like sq
24a50 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20  lite3_open().** 
24a60 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
24a70 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74  ccepts two addit
24a80 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73  ional parameters
24a90 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
24aa0 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20  control.** over 
24ab0 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
24ac0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28   connection.  ^(
24ad0 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  The flags parame
24ae0 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ter to.** sqlite
24af0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20  3_open_v2() can 
24b00 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74  take one of.** t
24b10 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72  he following thr
24b20 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f  ee values, optio
24b30 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
24b40 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ith the .** [SQL
24b50 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
24b60 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
24b70 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c  FULLMUTEX], [SQL
24b80 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
24b90 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ACHE],.** [SQLIT
24ba0 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
24bb0 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51  CHE], and/or [SQ
24bc0 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
24bd0 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64  lags:)^.**.** <d
24be0 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  l>.** ^(<dt>[SQL
24bf0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
24c00 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  Y]</dt>.** <dd>T
24c10 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
24c20 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e  pened in read-on
24c30 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  ly mode.  If the
24c40 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e   database does n
24c50 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78  ot.** already ex
24c60 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73  ist, an error is
24c70 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
24c80 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
24c90 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
24ca0 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RITE]</dt>.** <d
24cb0 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
24cc0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
24cd0 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
24ce0 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72   if possible, or
24cf0 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79   reading.** only
24d00 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   if the file is 
24d10 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20  write protected 
24d20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  by the operating
24d30 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74   system.  In eit
24d40 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20  her.** case the 
24d50 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c  database must al
24d60 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68  ready exist, oth
24d70 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20  erwise an error 
24d80 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
24d90 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
24da0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
24db0 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
24dc0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f  E_OPEN_CREATE]</
24dd0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
24de0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
24df0 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
24e00 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69  d writing, and i
24e10 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20  s created if.** 
24e20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65  it does not alre
24e30 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20  ady exist. This 
24e40 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  is the behavior 
24e50 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75  that is always u
24e60 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  sed for.** sqlit
24e70 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
24e80 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c  lite3_open16().<
24e90 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
24ea0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64  **.** If the 3rd
24eb0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
24ec0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
24ed0 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68  is not one of th
24ee0 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  e.** combination
24ef0 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70  s shown above op
24f00 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65  tionally combine
24f10 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20  d with other.** 
24f20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
24f30 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f  DONLY | SQLITE_O
24f40 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74  PEN_* bits].** t
24f50 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
24f60 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
24f70 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51  *.** ^If the [SQ
24f80 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
24f90 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20  X] flag is set, 
24fa0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
24fb0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
24fc0 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c  opens in the mul
24fd0 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
24fe0 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f  ding mode] as lo
24ff0 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65  ng as the single
25000 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20  -thread.** mode 
25010 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74  has not been set
25020 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
25030 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20   or start-time. 
25040 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c   ^If the.** [SQL
25050 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
25060 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20  EX] flag is set 
25070 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
25080 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65  e connection ope
25090 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72  ns.** in the ser
250a0 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
250b0 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20  ng mode] unless 
250c0 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61  single-thread wa
250d0 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  s.** previously 
250e0 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70  selected at comp
250f0 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
25100 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20  t-time..** ^The 
25110 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
25120 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63  REDCACHE] flag c
25130 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61  auses the databa
25140 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  se connection to
25150 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20   be.** eligible 
25160 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63  to use [shared c
25170 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61  ache mode], rega
25180 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
25190 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a  r or not shared.
251a0 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62  ** cache is enab
251b0 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  led using [sqlit
251c0 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
251d0 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65  _cache()].  ^The
251e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
251f0 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66  _PRIVATECACHE] f
25200 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64  lag causes the d
25210 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
25220 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72  on to not.** par
25230 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61  ticipate in [sha
25240 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20  red cache mode] 
25250 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e  even if it is en
25260 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  abled..**.** ^Th
25270 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
25280 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
25290 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e  en_v2() is the n
252a0 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ame of the.** [s
252b0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
252c0 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
252d0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
252e0 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74  stem interface t
252f0 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64  hat.** the new d
25300 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
25310 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20  on should use.  
25320 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70  ^If the fourth p
25330 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61  arameter is.** a
25340 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
25350 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  en the default [
25360 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
25370 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ect is used..**.
25380 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e  ** ^If the filen
25390 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a  ame is ":memory:
253a0 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  ", then a privat
253b0 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d  e, temporary in-
253c0 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a  memory database.
253d0 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f  ** is created fo
253e0 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  r the connection
253f0 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f  .  ^This in-memo
25400 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  ry database will
25410 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20   vanish when.** 
25420 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
25430 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
25440 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  d.  Future versi
25450 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
25460 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20  ght.** make use 
25470 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70  of additional sp
25480 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20  ecial filenames 
25490 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20  that begin with 
254a0 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65  the ":" characte
254b0 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f  r..** It is reco
254c0 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65  mmended that whe
254d0 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  n a database fil
254e0 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64  ename actually d
254f0 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a  oes begin with.*
25500 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65  * a ":" characte
25510 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65  r you should pre
25520 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  fix the filename
25530 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65   with a pathname
25540 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22   such as.** "./"
25550 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75   to avoid ambigu
25560 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ity..**.** ^If t
25570 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61  he filename is a
25580 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
25590 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
255a0 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d  temporary.** on-
255b0 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69  disk database wi
255c0 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20  ll be created.  
255d0 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61  ^This private da
255e0 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a  tabase will be.*
255f0 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
25600 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20  deleted as soon 
25610 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  as the database 
25620 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
25630 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52  osed..**.** [[UR
25640 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73  I filenames in s
25650 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20  qlite3_open()]] 
25660 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65  <h3>URI Filename
25670 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66  s</h3>.**.** ^If
25680 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20   [URI filename] 
25690 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
256a0 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74  s enabled, and t
256b0 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
256c0 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77  ment.** begins w
256d0 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65  ith "file:", the
256e0 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  n the filename i
256f0 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
25700 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20   a URI. ^URI.** 
25710 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72  filename interpr
25720 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  etation is enabl
25730 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  ed if the [SQLIT
25740 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
25750 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68   is.** set in th
25760 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
25770 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  t to sqlite3_ope
25780 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74  n_v2(), or if it
25790 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61   has.** been ena
257a0 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73  bled globally us
257b0 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
257c0 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69  CONFIG_URI] opti
257d0 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  on with the.** [
257e0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
257f0 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74  ] method or by t
25800 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55  he [SQLITE_USE_U
25810 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  RI] compile-time
25820 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f   option..** As o
25830 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  f SQLite version
25840 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65   3.7.7, URI file
25850 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74  name interpretat
25860 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66  ion is turned of
25870 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c  f.** by default,
25880 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65   but future rele
25890 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ases of SQLite m
258a0 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20  ight enable URI 
258b0 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65  filename.** inte
258c0 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65  rpretation by de
258d0 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52  fault.  See "[UR
258e0 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f  I filenames]" fo
258f0 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
25900 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
25910 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  ** URI filenames
25920 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f   are parsed acco
25930 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38  rding to RFC 398
25940 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63  6. ^If the URI c
25950 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75  ontains an.** au
25960 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74  thority, then it
25970 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
25980 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
25990 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a  or the string .*
259a0 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e  * "localhost". ^
259b0 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79  If the authority
259c0 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79   is not an empty
259d0 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61   string or "loca
259e0 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65  lhost", an .** e
259f0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
25a00 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20   to the caller. 
25a10 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f  ^The fragment co
25a20 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
25a30 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74  , if .** present
25a40 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  , is ignored..**
25a50 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
25a60 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e   the path compon
25a70 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61  ent of the URI a
25a80 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
25a90 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77  e disk file.** w
25aa0 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68  hich contains th
25ab0 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20  e database. ^If 
25ac0 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20  the path begins 
25ad0 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61  with a '/' chara
25ae0 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69  cter, .** then i
25af0 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
25b00 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20   as an absolute 
25b10 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61  path. ^If the pa
25b20 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69  th does not begi
25b30 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27  n .** with a '/'
25b40 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74   (meaning that t
25b50 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63  he authority sec
25b60 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20  tion is omitted 
25b70 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a  from the URI).**
25b80 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69   then the path i
25b90 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
25ba0 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68   a relative path
25bb0 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f  . .** ^(On windo
25bc0 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f  ws, the first co
25bd0 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62  mponent of an ab
25be0 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20  solute path .** 
25bf0 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69  is a drive speci
25c00 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22  fication (e.g. "
25c10 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  C:").)^.**.** [[
25c20 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70  core URI query p
25c30 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54  arameters]].** T
25c40 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  he query compone
25c50 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20  nt of a URI may 
25c60 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65  contain paramete
25c70 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  rs that are inte
25c80 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65  rpreted.** eithe
25c90 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65  r by SQLite itse
25ca0 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53  lf, or by a [VFS
25cb0 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d   | custom VFS im
25cc0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a  plementation]..*
25cd0 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 69 74 73  * SQLite and its
25ce0 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73   built-in [VFSes
25cf0 5d 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a  ] interpret the.
25d00 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65  ** following que
25d10 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a  ry parameters:.*
25d20 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  *.** <ul>.**   <
25d30 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20  li> <b>vfs</b>: 
25d40 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d  ^The "vfs" param
25d50 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64  eter may be used
25d60 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20   to specify the 
25d70 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61  name of.**     a
25d80 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74   VFS object that
25d90 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70   provides the op
25da0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
25db0 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68  nterface that sh
25dc0 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75  ould.**     be u
25dd0 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68  sed to access th
25de0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
25df0 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69  on disk. ^If thi
25e00 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20  s option is set 
25e10 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70  to.**     an emp
25e20 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65  ty string the de
25e30 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74  fault VFS object
25e40 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69   is used. ^Speci
25e50 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e  fying an unknown
25e60 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61  .**     VFS is a
25e70 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c  n error. ^If sql
25e80 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
25e90 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76  s used and the v
25ea0 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  fs option is.** 
25eb0 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65      present, the
25ec0 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66  n the VFS specif
25ed0 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f  ied by the optio
25ee0 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e  n takes preceden
25ef0 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74  ce over.**     t
25f00 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  he value passed 
25f10 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  as the fourth pa
25f20 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
25f30 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
25f40 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f  .**   <li> <b>mo
25f50 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f  de</b>: ^(The mo
25f60 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  de parameter may
25f70 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65   be set to eithe
25f80 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a  r "ro", "rw",.**
25f90 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22       "rwc", or "
25fa0 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74  memory". Attempt
25fb0 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f  ing to set it to
25fc0 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65   any other value
25fd0 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72   is.**     an er
25fe0 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e  ror)^. .**     ^
25ff0 49 66 20 22 72 6f 22 20 69 73 20 73 70 65 63 69  If "ro" is speci
26000 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64  fied, then the d
26010 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
26020 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20  d for read-only 
26030 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20  .**     access, 
26040 6a 75 73 74 20 61 73 20 69 66 20 74 68 65 20 5b  just as if the [
26050 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
26060 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62  ONLY] flag had b
26070 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a  een set in the .
26080 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61 72 67  **     third arg
26090 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
260a0 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20  _open_v2(). ^If 
260b0 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20  the mode option 
260c0 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20  is set to .**   
260d0 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65    "rw", then the
260e0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
260f0 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69  ned for read-wri
26100 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61  te (but not crea
26110 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65  te) .**     acce
26120 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45  ss, as if SQLITE
26130 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
26140 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f  (but not SQLITE_
26150 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64  OPEN_CREATE) had
26160 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65   .**     been se
26170 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20  t. ^Value "rwc" 
26180 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f  is equivalent to
26190 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a   setting both .*
261a0 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
261b0 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20  N_READWRITE and 
261c0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
261d0 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64  TE.  ^If the mod
261e0 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20  e option is.**  
261f0 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72     set to "memor
26200 79 22 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b  y" then a pure [
26210 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
26220 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72  se] that never r
26230 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77  eads.**     or w
26240 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20  rites from disk 
26250 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20  is used. ^It is 
26260 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63  an error to spec
26270 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a  ify a value for.
26280 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20  **     the mode 
26290 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69  parameter that i
262a0 73 20 6c 65 73 73 20 72 65 73 74 72 69 63 74 69  s less restricti
262b0 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 70 65  ve than that spe
262c0 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20  cified by.**    
262d0 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 73 65   the flags passe
262e0 64 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70  d in the third p
262f0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
26300 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
26310 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63  *.**   <li> <b>c
26320 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63  ache</b>: ^The c
26330 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d  ache parameter m
26340 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74  ay be set to eit
26350 68 65 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a  her "shared" or.
26360 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74 65 22  **     "private"
26370 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f  . ^Setting it to
26380 20 22 73 68 61 72 65 64 22 20 69 73 20 65 71 75   "shared" is equ
26390 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69  ivalent to setti
263a0 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51  ng the.**     SQ
263b0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
263c0 43 41 43 48 45 20 62 69 74 20 69 6e 20 74 68 65  CACHE bit in the
263d0 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
263e0 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20  passed to.**    
263f0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
26400 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65  (). ^Setting the
26410 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72   cache parameter
26420 20 74 6f 20 22 70 72 69 76 61 74 65 22 20 69 73   to "private" is
26430 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c   .**     equival
26440 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74  ent to setting t
26450 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  he SQLITE_OPEN_P
26460 52 49 56 41 54 45 43 41 43 48 45 20 62 69 74 2e  RIVATECACHE bit.
26470 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69  .**     ^If sqli
26480 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
26490 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 22 63   used and the "c
264a0 61 63 68 65 22 20 70 61 72 61 6d 65 74 65 72 20  ache" parameter 
264b0 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a  is present in.**
264c0 20 20 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e       a URI filen
264d0 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f  ame, its value o
264e0 76 65 72 72 69 64 65 73 20 61 6e 79 20 62 65 68  verrides any beh
264f0 61 76 69 6f 72 20 72 65 71 75 65 73 74 65 64 20  avior requested 
26500 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20  by setting.**   
26510 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52    SQLITE_OPEN_PR
26520 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 51  IVATECACHE or SQ
26530 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
26540 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a  CACHE flag..**.*
26550 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c  *  <li> <b>psow<
26560 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20 70  /b>: ^The psow p
26570 61 72 61 6d 65 74 65 72 20 69 6e 64 69 63 61 74  arameter indicat
26580 65 73 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  es whether or no
26590 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f  t the.**     [po
265a0 77 65 72 73 61 66 65 20 6f 76 65 72 77 72 69 74  wersafe overwrit
265b0 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65 73  e] property does
265c0 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70 70   or does not app
265d0 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20  ly to the.**    
265e0 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20 6f   storage media o
265f0 6e 20 77 68 69 63 68 20 74 68 65 20 64 61 74 61  n which the data
26600 62 61 73 65 20 66 69 6c 65 20 72 65 73 69 64 65  base file reside
26610 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c  s..**.**  <li> <
26620 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54  b>nolock</b>: ^T
26630 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65  he nolock parame
26640 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e  ter is a boolean
26650 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
26660 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 20 69 66  .**     which if
26670 20 73 65 74 20 64 69 73 61 62 6c 65 73 20 66 69   set disables fi
26680 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f  le locking in ro
26690 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d  llback journal m
266a0 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20  odes.  This.**  
266b0 20 20 20 69 73 20 75 73 65 66 75 6c 20 66 6f 72     is useful for
266c0 20 61 63 63 65 73 73 69 6e 67 20 61 20 64 61 74   accessing a dat
266d0 61 62 61 73 65 20 6f 6e 20 61 20 66 69 6c 65 73  abase on a files
266e0 79 73 74 65 6d 20 74 68 61 74 20 64 6f 65 73 20  ystem that does 
266f0 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f  not.**     suppo
26700 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75  rt locking.  Cau
26710 74 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 65 20  tion:  Database 
26720 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 68 74  corruption might
26730 20 72 65 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a   result if two.*
26740 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 70 72  *     or more pr
26750 6f 63 65 73 73 65 73 20 77 72 69 74 65 20 74 6f  ocesses write to
26760 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
26770 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f  se and any one o
26780 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70  f those.**     p
26790 72 6f 63 65 73 73 65 73 20 75 73 65 73 20 6e 6f  rocesses uses no
267a0 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c  lock=1..**.**  <
267b0 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65  li> <b>immutable
267c0 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74  </b>: ^The immut
267d0 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72 20 69  able parameter i
267e0 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72  s a boolean quer
267f0 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74  y.**     paramet
26800 65 72 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  er that indicate
26810 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62  s that the datab
26820 61 73 65 20 66 69 6c 65 20 69 73 20 73 74 6f 72  ase file is stor
26830 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61  ed on.**     rea
26840 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e  d-only media.  ^
26850 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69  When immutable i
26860 73 20 73 65 74 2c 20 53 51 4c 69 74 65 20 61 73  s set, SQLite as
26870 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
26880 2a 20 20 20 20 20 64 61 74 61 62 61 73 65 20 66  *     database f
26890 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63 68  ile cannot be ch
268a0 61 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 20 61  anged, even by a
268b0 20 70 72 6f 63 65 73 73 20 77 69 74 68 20 68 69   process with hi
268c0 67 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 69 76  gher.**     priv
268d0 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 74 68  ilege, and so th
268e0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
268f0 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61  ened read-only a
26900 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a  nd all locking.*
26910 2a 20 20 20 20 20 61 6e 64 20 63 68 61 6e 67 65  *     and change
26920 20 64 65 74 65 63 74 69 6f 6e 20 69 73 20 64 69   detection is di
26930 73 61 62 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e  sabled.  Caution
26940 3a 20 53 65 74 74 69 6e 67 20 74 68 65 20 69 6d  : Setting the im
26950 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70  mutable.**     p
26960 72 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 61 74  roperty on a dat
26970 61 62 61 73 65 20 66 69 6c 65 20 74 68 61 74 20  abase file that 
26980 64 6f 65 73 20 69 6e 20 66 61 63 74 20 63 68 61  does in fact cha
26990 6e 67 65 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a  nge can result.*
269a0 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 72 65  *     in incorre
269b0 63 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  ct query results
269c0 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f   and/or [SQLITE_
269d0 43 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 73 2e  CORRUPT] errors.
269e0 0a 2a 2a 20 20 20 20 20 53 65 65 20 61 6c 73 6f  .**     See also
269f0 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  : [SQLITE_IOCAP_
26a00 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20  IMMUTABLE]..**  
26a10 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a       .** </ul>.*
26a20 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67  *.** ^Specifying
26a30 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61   an unknown para
26a40 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 65  meter in the que
26a50 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  ry component of 
26a60 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a  a URI is not an.
26a70 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72  ** error.  Futur
26a80 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
26a90 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72  Lite might under
26aa0 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c  stand additional
26ab0 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65   query.** parame
26ac0 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65  ters.  See "[que
26ad0 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 69  ry parameters wi
26ae0 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69  th special meani
26af0 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66  ng to SQLite]" f
26b00 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c  or.** additional
26b10 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
26b20 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61  .** [[URI filena
26b30 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68  me examples]] <h
26b40 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65  3>URI filename e
26b50 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a  xamples</h3>.**.
26b60 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
26b70 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65  ="1" align=cente
26b80 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e  r cellpadding=5>
26b90 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49  .** <tr><th> URI
26ba0 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20   filenames <th> 
26bb0 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c  Results.** <tr><
26bc0 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
26bd0 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
26be0 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65     Open the file
26bf0 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68   "data.db" in th
26c00 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74  e current direct
26c10 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ory..** <tr><td>
26c20 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64   file:/home/fred
26c30 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20  /data.db<br>.** 
26c40 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
26c50 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
26c60 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20  db <br> .**     
26c70 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61       file://loca
26c80 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f  lhost/home/fred/
26c90 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64  data.db <br> <td
26ca0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
26cb0 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
26cc0 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65   file "/home/fre
26cd0 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c  d/data.db"..** <
26ce0 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64  tr><td> file://d
26cf0 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65  arkstar/home/fre
26d00 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a  d/data.db <td> .
26d10 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65  **          An e
26d20 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22  rror. "darkstar"
26d30 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e   is not a recogn
26d40 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a  ized authority..
26d50 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65  ** <tr><td style
26d60 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f  ="white-space:no
26d70 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20  wrap"> .**      
26d80 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44      file:///C:/D
26d90 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32  ocuments%20and%2
26da0 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44  0Settings/fred/D
26db0 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a  esktop/data.db.*
26dc0 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f  *     <td> Windo
26dd0 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68  ws only: Open th
26de0 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  e file "data.db"
26df0 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74   on fred's deskt
26e00 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20  op on drive.**  
26e10 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65          C:. Note
26e20 20 74 68 61 74 20 74 68 65 20 25 32 30 20 65 73   that the %20 es
26e30 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65  caping in this e
26e40 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74  xample is not st
26e50 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20  rictly .**      
26e60 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20      necessary - 
26e70 73 70 61 63 65 20 63 68 61 72 61 63 74 65 72 73  space characters
26e80 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74   can be used lit
26e90 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20  erally.**       
26ea0 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61     in URI filena
26eb0 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  mes..** <tr><td>
26ec0 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f   file:data.db?mo
26ed0 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76  de=ro&cache=priv
26ee0 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  ate <td> .**    
26ef0 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20        Open file 
26f00 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65  "data.db" in the
26f10 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f   current directo
26f20 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79  ry for read-only
26f30 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20   access..**     
26f40 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 20       Regardless 
26f50 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
26f60 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d  t shared-cache m
26f70 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62  ode is enabled b
26f80 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65  y.**          de
26f90 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69  fault, use a pri
26fa0 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c  vate cache..** <
26fb0 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f  tr><td> file:/ho
26fc0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f  me/fred/data.db?
26fd0 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65  vfs=unix-dotfile
26fe0 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20   <td>.**        
26ff0 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f    Open file "/ho
27000 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22  me/fred/data.db"
27010 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69 61  . Use the specia
27020 6c 20 56 46 53 20 22 75 6e 69 78 2d 64 6f 74 66  l VFS "unix-dotf
27030 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 20 20  ile".**         
27040 20 74 68 61 74 20 75 73 65 73 20 64 6f 74 2d 66   that uses dot-f
27050 69 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66  iles in place of
27060 20 70 6f 73 69 78 20 61 64 76 69 73 6f 72 79 20   posix advisory 
27070 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e  locking..** <tr>
27080 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
27090 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20  b?mode=readonly 
270a0 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
270b0 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61    An error. "rea
270c0 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20  donly" is not a 
270d0 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72  valid option for
270e0 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61   the "mode" para
270f0 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c  meter..** </tabl
27100 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65  e>.**.** ^URI he
27110 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
27120 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48 29   sequences (%HH)
27130 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 77   are supported w
27140 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 61  ithin the path a
27150 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70  nd.** query comp
27160 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e  onents of a URI.
27170 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65   A hexadecimal e
27180 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 63  scape sequence c
27190 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20  onsists of a.** 
271a0 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22  percent sign - "
271b0 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79  %" - followed by
271c0 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78   exactly two hex
271d0 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20  adecimal digits 
271e0 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61  .** specifying a
271f0 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e  n octet value. ^
27200 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 20  Before the path 
27210 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  or query compone
27220 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20  nts of a.** URI 
27230 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74  filename are int
27240 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 61  erpreted, they a
27250 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67  re encoded using
27260 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a   UTF-8 and all .
27270 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65  ** hexadecimal e
27280 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20  scape sequences 
27290 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 69  replaced by a si
272a0 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69  ngle byte contai
272b0 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72  ning the.** corr
272c0 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e  esponding octet.
272d0 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 73   If this process
272e0 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e   generates an in
272f0 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f  valid UTF-8 enco
27300 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73  ding,.** the res
27310 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
27320 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ed..**.** <b>Not
27330 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65  e to Windows use
27340 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63  rs:</b>  The enc
27350 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74  oding used for t
27360 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
27370 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  ment.** of sqlit
27380 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
27390 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
273a0 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e  must be UTF-8, n
273b0 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63  ot whatever.** c
273c0 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65  odepage is curre
273d0 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46  ntly defined.  F
273e0 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e  ilenames contain
273f0 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61  ing internationa
27400 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  l.** characters 
27410 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
27420 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72  d to UTF-8 prior
27430 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d   to passing them
27440 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   into.** sqlite3
27450 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
27460 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
27470 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
27480 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75  indows Runtime u
27490 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74  sers:</b>  The t
274a0 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f  emporary directo
274b0 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a  ry must be set.*
274c0 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  * prior to calli
274d0 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ng sqlite3_open(
274e0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
274f0 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69  n_v2().  Otherwi
27500 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66  se, various.** f
27510 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65 71  eatures that req
27520 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 20  uire the use of 
27530 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20  temporary files 
27540 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20  may fail..**.** 
27550 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
27560 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72  e3_temp_director
27570 79 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  y].*/.SQLITE_API
27580 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
27590 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ALL sqlite3_open
275a0 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
275b0 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
275c0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
275d0 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
275e0 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
275f0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
27600 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
27610 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  /.);.SQLITE_API 
27620 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
27630 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  LL sqlite3_open1
27640 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  6(.  const void 
27650 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
27660 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
27670 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20  e (UTF-16) */.  
27680 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
27690 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
276a0 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
276b0 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
276c0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
276d0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 70 65  CALL sqlite3_ope
276e0 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68  n_v2(.  const ch
276f0 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
27700 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
27710 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
27720 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
27730 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54  ,         /* OUT
27740 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
27750 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67  le */.  int flag
27760 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  s,              
27770 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f  /* Flags */.  co
27780 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20  nst char *zVfs  
27790 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
277a0 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75   VFS module to u
277b0 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  se */.);../*.** 
277c0 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
277d0 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20   Values For URI 
277e0 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a  Parameters.**.**
277f0 20 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69   These are utili
27800 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65  ty routines, use
27810 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65  ful to VFS imple
27820 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74  mentations, that
27830 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65   check.** to see
27840 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66   if a database f
27850 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68  ile was a URI th
27860 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73  at contained a s
27870 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a  pecific query .*
27880 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64  * parameter, and
27890 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74   if so obtains t
278a0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74  he value of that
278b0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
278c0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20  ..**.** If F is 
278d0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
278e0 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61  ename pointer pa
278f0 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f  ssed into the xO
27900 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20  pen() method of 
27910 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d  .** a VFS implem
27920 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68  entation when th
27930 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
27940 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73  r to xOpen() has
27950 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65   one or .** more
27960 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
27970 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51  OPEN_URI] or [SQ
27980 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
27990 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a  B] bits set and.
279a0 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65  ** P is the name
279b0 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61   of the query pa
279c0 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a  rameter, then.**
279d0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
279e0 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
279f0 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66  rns the value of
27a00 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65   the P.** parame
27a10 74 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73  ter if it exists
27a20 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   or a NULL point
27a30 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74  er if P does not
27a40 20 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a   appear as a .**
27a50 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
27a60 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20   on F.  If P is 
27a70 61 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  a query paramete
27a80 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f  r of F.** has no
27a90 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c   explicit value,
27aa0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
27ab0 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
27ac0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f   returns.** a po
27ad0 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74  inter to an empt
27ae0 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  y string..**.** 
27af0 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  The sqlite3_uri_
27b00 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
27b10 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74  outine assumes t
27b20 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65  hat P is a boole
27b30 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  an.** parameter 
27b40 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65  and returns true
27b50 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30   (1) or false (0
27b60 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74  ) according to t
27b70 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50  he value.** of P
27b80 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  .  The sqlite3_u
27b90 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
27ba0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
27bb0 73 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68  s true (1) if th
27bc0 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75  e.** value of qu
27bd0 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20  ery parameter P 
27be0 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c  is one of "yes",
27bf0 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22   "true", or "on"
27c00 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20   in any.** case 
27c10 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  or if the value 
27c20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f  begins with a no
27c30 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20  n-zero number.  
27c40 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  The .** sqlite3_
27c50 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
27c60 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  B) routines retu
27c70 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66  rns false (0) if
27c80 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a   the value of.**
27c90 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
27ca0 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f   P is one of "no
27cb0 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22  ", "false", or "
27cc0 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65  off" in any case
27cd0 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61   or.** if the va
27ce0 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20  lue begins with 
27cf0 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20  a numeric zero. 
27d00 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71   If P is not a q
27d10 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65  uery.** paramete
27d20 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65  r on F or if the
27d30 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64   value of P is d
27d40 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e  oes not match an
27d50 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76  y of the.** abov
27d60 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  e, then sqlite3_
27d70 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
27d80 42 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30  B) returns (B!=0
27d90 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )..**.** The sql
27da0 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46  ite3_uri_int64(F
27db0 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f  ,P,D) routine co
27dc0 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65  nverts the value
27dd0 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20   of P into a.** 
27de0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
27df0 74 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e  teger and return
27e00 73 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20  s that integer, 
27e10 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e  or D if P does n
27e20 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66  ot.** exist.  If
27e30 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
27e40 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  is something oth
27e50 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67  er than an integ
27e60 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f  er, then.** zero
27e70 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
27e80 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e   .** If F is a N
27e90 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
27ea0 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  n sqlite3_uri_pa
27eb0 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
27ec0 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a  urns NULL and.**
27ed0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
27ee0 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75  lean(F,P,B) retu
27ef0 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20  rns B.  If F is 
27f00 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  not a NULL point
27f10 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74  er and.** is not
27f20 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
27f30 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65   pathname pointe
27f40 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61  r that SQLite pa
27f50 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f  ssed into the xO
27f60 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f  pen.** VFS metho
27f70 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  d, then the beha
27f80 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75  vior of this rou
27f90 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65  tine is undefine
27fa0 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a  d and probably.*
27fb0 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a  * undesirable..*
27fc0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
27fd0 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f  st char *SQLITE_
27fe0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
27ff0 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f  uri_parameter(co
28000 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
28010 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ame, const char 
28020 2a 7a 50 61 72 61 6d 29 3b 0a 53 51 4c 49 54 45  *zParam);.SQLITE
28030 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
28040 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
28050 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73  uri_boolean(cons
28060 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63  t char *zFile, c
28070 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61  onst char *zPara
28080 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29  m, int bDefault)
28090 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  ;.SQLITE_API sql
280a0 69 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54  ite3_int64 SQLIT
280b0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
280c0 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73  3_uri_int64(cons
280d0 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63  t char*, const c
280e0 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  har*, sqlite3_in
280f0 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  t64);.../*.** CA
28100 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f  PI3REF: Error Co
28110 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73  des And Messages
28120 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
28130 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  te3.**.** ^If th
28140 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 71  e most recent sq
28150 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c  lite3_* API call
28160 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
28170 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63   .** [database c
28180 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61 69  onnection] D fai
28190 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 73 71  led, then the sq
281a0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29  lite3_errcode(D)
281b0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65   interface.** re
281c0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69  turns the numeri
281d0 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  c [result code] 
281e0 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  or [extended res
281f0 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ult code] for th
28200 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e 0a  at.** API call..
28210 2a 2a 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72  ** If the most r
28220 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 77  ecent API call w
28230 61 73 20 73 75 63 63 65 73 73 66 75 6c 2c 0a 2a  as successful,.*
28240 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72  * then the retur
28250 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  n value from sql
28260 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69  ite3_errcode() i
28270 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
28280 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74  ^The sqlite3_ext
28290 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a  ended_errcode().
282a0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
282b0 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20  the same except 
282c0 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72  that it always r
282d0 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b  eturns the .** [
282e0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
282f0 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20  code] even when 
28300 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
28310 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73  codes are.** dis
28320 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  abled..**.** ^Th
28330 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  e sqlite3_errmsg
28340 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65  () and sqlite3_e
28350 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e  rrmsg16() return
28360 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
28370 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64  e.** text that d
28380 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
28390 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54  or, as either UT
283a0 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65  F-8 or UTF-16 re
283b0 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
283c0 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20  (Memory to hold 
283d0 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
283e0 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
283f0 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a  ged internally..
28400 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
28410 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  on does not need
28420 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20   to worry about 
28430 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75  freeing the resu
28440 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  lt..** However, 
28450 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67  the error string
28460 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72   might be overwr
28470 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  itten or dealloc
28480 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65  ated by.** subse
28490 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f  quent calls to o
284a0 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
284b0 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e  rface functions.
284c0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
284d0 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69  lite3_errstr() i
284e0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
284f0 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e   the English-lan
28500 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68  guage text.** th
28510 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65  at describes the
28520 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20   [result code], 
28530 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d  as UTF-8..** ^(M
28540 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
28550 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
28560 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65  string is manage
28570 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20  d internally.** 
28580 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20  and must not be 
28590 66 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70  freed by the app
285a0 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a  lication)^..**.*
285b0 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61  * When the seria
285c0 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
285d0 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65   mode] is in use
285e0 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68  , it might be th
285f0 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61  e.** case that a
28600 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63   second error oc
28610 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61  curs on a separa
28620 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74  te thread in bet
28630 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65  ween.** the time
28640 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72   of the first er
28650 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  ror and the call
28660 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
28670 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68  aces..** When th
28680 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20  at happens, the 
28690 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c  second error wil
286a0 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69  l be reported si
286b0 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74  nce these.** int
286c0 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72  erfaces always r
286d0 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72  eport the most r
286e0 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54  ecent result.  T
286f0 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c  o avoid.** this,
28700 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e   each thread can
28710 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76   obtain exclusiv
28720 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61  e use of the [da
28730 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
28740 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b  n] D.** by invok
28750 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
28760 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74  ex_enter]([sqlit
28770 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
28780 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e   before beginnin
28790 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e  g.** to use D an
287a0 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  d invoking [sqli
287b0 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d  te3_mutex_leave]
287c0 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
287d0 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a  ex](D)) after.**
287e0 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68   all calls to th
287f0 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73  e interfaces lis
28800 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d  ted here are com
28810 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  pleted..**.** If
28820 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61   an interface fa
28830 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f  ils with SQLITE_
28840 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61  MISUSE, that mea
28850 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  ns the interface
28860 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20  .** was invoked 
28870 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74  incorrectly by t
28880 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
28890 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74   In that case, t
288a0 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65  he.** error code
288b0 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79   and message may
288c0 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73   or may not be s
288d0 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  et..*/.SQLITE_AP
288e0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
288f0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 72 72  CALL sqlite3_err
28900 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
28910 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
28920 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
28930 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
28940 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  d_errcode(sqlite
28950 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41  3 *db);.SQLITE_A
28960 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53  PI const char *S
28970 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
28980 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c  lite3_errmsg(sql
28990 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  ite3*);.SQLITE_A
289a0 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53  PI const void *S
289b0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
289c0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73  lite3_errmsg16(s
289d0 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45  qlite3*);.SQLITE
289e0 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
289f0 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
28a00 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69  sqlite3_errstr(i
28a10 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
28a20 33 52 45 46 3a 20 50 72 65 70 61 72 65 64 20 53  3REF: Prepared S
28a30 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
28a40 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
28a50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28a60 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  } {prepared stat
28a70 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e  ements}.**.** An
28a80 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
28a90 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  s object represe
28aa0 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  nts a single SQL
28ab0 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 0a   statement that.
28ac0 2a 2a 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 70  ** has been comp
28ad0 69 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61 72 79  iled into binary
28ae0 20 66 6f 72 6d 20 61 6e 64 20 69 73 20 72 65 61   form and is rea
28af0 64 79 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  dy to be evaluat
28b00 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20  ed..**.** Think 
28b10 6f 66 20 65 61 63 68 20 53 51 4c 20 73 74 61 74  of each SQL stat
28b20 65 6d 65 6e 74 20 61 73 20 61 20 73 65 70 61 72  ement as a separ
28b30 61 74 65 20 63 6f 6d 70 75 74 65 72 20 70 72 6f  ate computer pro
28b40 67 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72  gram.  The.** or
28b50 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 20  iginal SQL text 
28b60 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20  is source code. 
28b70 20 41 20 70 72 65 70 61 72 65 64 20 73 74 61 74   A prepared stat
28b80 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a  ement object .**
28b90 20 69 73 20 74 68 65 20 63 6f 6d 70 69 6c 65 64   is the compiled
28ba0 20 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20 20 41   object code.  A
28bb0 6c 6c 20 53 51 4c 20 6d 75 73 74 20 62 65 20 63  ll SQL must be c
28bc0 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 0a  onverted into a.
28bd0 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ** prepared stat
28be0 65 6d 65 6e 74 20 62 65 66 6f 72 65 20 69 74 20  ement before it 
28bf0 63 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a  can be run..**.*
28c00 2a 20 54 68 65 20 6c 69 66 65 2d 63 79 63 6c 65  * The life-cycle
28c10 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 20 73   of a prepared s
28c20 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
28c30 75 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b  usually goes lik
28c40 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e this:.**.** <o
28c50 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74  l>.** <li> Creat
28c60 65 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  e the prepared s
28c70 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
28c80 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
28c90 72 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a  repare_v2()]..**
28ca0 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65   <li> Bind value
28cb0 73 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 73  s to [parameters
28cc0 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  ] using the sqli
28cd0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20  te3_bind_*().** 
28ce0 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e       interfaces.
28cf0 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65  .** <li> Run the
28d00 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20   SQL by calling 
28d10 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
28d20 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
28d30 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65  es..** <li> Rese
28d40 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  t the prepared s
28d50 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
28d60 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
28d70 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a   then go back.**
28d80 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e        to step 2.
28d90 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f    Do this zero o
28da0 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
28db0 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68   <li> Destroy th
28dc0 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
28dd0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
28de0 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f  ()]..** </ol>.*/
28df0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
28e00 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c  sqlite3_stmt sql
28e10 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a  ite3_stmt;../*.*
28e20 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
28e30 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d  time Limits.** M
28e40 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
28e50 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65  *.** ^(This inte
28e60 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65  rface allows the
28e70 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73   size of various
28e80 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
28e90 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20  e limited.** on 
28ea0 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20  a connection by 
28eb0 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73  connection basis
28ec0 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72  .  The first par
28ed0 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
28ee0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
28ef0 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d  ction] whose lim
28f00 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20  it is to be set 
28f10 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65  or queried.  The
28f20 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
28f30 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74  eter is one of t
28f40 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f  he [limit catego
28f50 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e  ries] that defin
28f60 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20  e a.** class of 
28f70 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
28f80 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20   size limited.  
28f90 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
28fa0 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65  ter is the.** ne
28fb0 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74  w limit for that
28fc0 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a   construct.)^.**
28fd0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20  .** ^If the new 
28fe0 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74  limit is a negat
28ff0 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20  ive number, the 
29000 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67  limit is unchang
29010 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63  ed..** ^(For eac
29020 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79  h limit category
29030 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69   SQLITE_LIMIT_<i
29040 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20  >NAME</i> there 
29050 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73  is a .** [limits
29060 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f   | hard upper bo
29070 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63  und].** set at c
29080 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61  ompile-time by a
29090 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
290a0 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20  macro called.** 
290b0 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45  [limits | SQLITE
290c0 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  _MAX_<i>NAME</i>
290d0 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d  ]..** (The "_LIM
290e0 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65  IT_" in the name
290f0 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22   is changed to "
29100 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41  _MAX_".))^.** ^A
29110 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65  ttempts to incre
29120 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76  ase a limit abov
29130 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72  e its hard upper
29140 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69   bound are.** si
29150 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
29160 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70   to the hard upp
29170 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20  er bound..**.** 
29180 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77  ^Regardless of w
29190 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
291a0 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e  e limit was chan
291b0 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71  ged, the .** [sq
291c0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69  lite3_limit()] i
291d0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
291e0 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65   the prior value
291f0 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a   of the limit..*
29200 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e  * ^Hence, to fin
29210 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  d the current va
29220 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77  lue of a limit w
29230 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20  ithout changing 
29240 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e  it,.** simply in
29250 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66  voke this interf
29260 61 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69  ace with the thi
29270 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74  rd parameter set
29280 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75   to -1..**.** Ru
29290 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72  n-time limits ar
292a0 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
292b0 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f  se in applicatio
292c0 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a  ns that manage.*
292d0 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e  * both their own
292e0 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
292f0 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61  se and also data
29300 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63  bases that are c
29310 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20  ontrolled.** by 
29320 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e  untrusted extern
29330 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20  al sources.  An 
29340 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74  example applicat
29350 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a  ion might be a.*
29360 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68  * web browser th
29370 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64  at has its own d
29380 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f  atabases for sto
29390 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64  ring history and
293a0 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74  .** separate dat
293b0 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65  abases controlle
293c0 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20  d by JavaScript 
293d0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77  applications dow
293e0 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74  nloaded.** off t
293f0 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68  he Internet.  Th
29400 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  e internal datab
29410 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65  ases can be give
29420 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20  n the.** large, 
29430 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20  default limits. 
29440 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67   Databases manag
29450 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73  ed by external s
29460 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65  ources can.** be
29470 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c   given much smal
29480 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67  ler limits desig
29490 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61  ned to prevent a
294a0 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69   denial of servi
294b0 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44  ce.** attack.  D
294c0 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20  evelopers might 
294d0 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65  also want to use
294e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   the [sqlite3_se
294f0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a  t_authorizer()].
29500 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  ** interface to 
29510 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20  further control 
29520 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20  untrusted SQL.  
29530 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
29540 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61  database.** crea
29550 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73  ted by an untrus
29560 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62  ted script can b
29570 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e  e contained usin
29580 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61  g the.** [max_pa
29590 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
295a0 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75  A]..**.** New ru
295b0 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74  n-time limit cat
295c0 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61  egories may be a
295d0 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
295e0 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49  eleases..*/.SQLI
295f0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
29600 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
29610 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a  3_limit(sqlite3*
29620 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65  , int id, int ne
29630 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  wVal);../*.** CA
29640 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
29650 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65   Limit Categorie
29660 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
29670 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20  limit category} 
29680 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  {*limit categori
29690 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  es}.**.** These 
296a0 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
296b0 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d   various perform
296c0 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74  ance limits.** t
296d0 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72  hat can be lower
296e0 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75  ed at run-time u
296f0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
29700 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  mit()]..** The s
29710 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d  ynopsis of the m
29720 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76  eanings of the v
29730 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73  arious limits is
29740 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a   shown below..**
29750 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   Additional info
29760 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c  rmation is avail
29770 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20  able at [limits 
29780 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69  | Limits in SQLi
29790 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  te]..**.** <dl>.
297a0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
297b0 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74  T_LENGTH]] ^(<dt
297c0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  >SQLITE_LIMIT_LE
297d0 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
297e0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a  >The maximum siz
297f0 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20  e of any string 
29800 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65  or BLOB or table
29810 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c   row, in bytes.<
29820 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
29830 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
29840 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
29850 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
29860 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
29870 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
29880 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73  ngth of an SQL s
29890 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74  tatement, in byt
298a0 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  es.</dd>)^.**.**
298b0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
298c0 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53  COLUMN]] ^(<dt>S
298d0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
298e0 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  MN</dt>.** <dd>T
298f0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
29900 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
29910 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69  a table definiti
29920 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20  on or in the.** 
29930 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
29940 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20  [SELECT] or the 
29950 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
29960 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20  f columns in an 
29970 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61  index.** or in a
29980 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52  n ORDER BY or GR
29990 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f  OUP BY clause.</
299a0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
299b0 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
299c0 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
299d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
299e0 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  DEPTH</dt>.** <d
299f0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  d>The maximum de
29a00 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65  pth of the parse
29a10 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70   tree on any exp
29a20 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a  ression.</dd>)^.
29a30 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
29a40 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
29a50 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  LECT]] ^(<dt>SQL
29a60 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
29a70 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a  ND_SELECT</dt>.*
29a80 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
29a90 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d  m number of term
29aa0 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20  s in a compound 
29ab0 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
29ac0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
29ad0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44  [SQLITE_LIMIT_VD
29ae0 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51  BE_OP]] ^(<dt>SQ
29af0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
29b00 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  OP</dt>.** <dd>T
29b10 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
29b20 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e  r of instruction
29b30 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d  s in a virtual m
29b40 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a  achine program.*
29b50 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  * used to implem
29b60 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65  ent an SQL state
29b70 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69  ment.  This limi
29b80 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  t is not current
29b90 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20  ly.** enforced, 
29ba0 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68  though that migh
29bb0 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f  t be added in so
29bc0 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  me future releas
29bd0 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c  e of.** SQLite.<
29be0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
29bf0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
29c00 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74  TION_ARG]] ^(<dt
29c10 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  >SQLITE_LIMIT_FU
29c20 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a  NCTION_ARG</dt>.
29c30 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
29c40 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  um number of arg
29c50 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63  uments on a func
29c60 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  tion.</dd>)^.**.
29c70 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
29c80 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c  T_ATTACHED]] ^(<
29c90 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
29ca0 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a  ATTACHED</dt>.**
29cb0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
29cc0 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41   number of [ATTA
29cd0 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61  CH | attached da
29ce0 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e  tabases].)^</dd>
29cf0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
29d00 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
29d10 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e  RN_LENGTH]].** ^
29d20 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
29d30 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
29d40 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
29d50 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
29d60 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74  ngth of the patt
29d70 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ern argument to 
29d80 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a  the [LIKE] or.**
29d90 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
29da0 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
29db0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  [[SQLITE_LIMIT_V
29dc0 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d  ARIABLE_NUMBER]]
29dd0 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
29de0 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
29df0 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  NUMBER</dt>.** <
29e00 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69  dd>The maximum i
29e10 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61  ndex number of a
29e20 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69  ny [parameter] i
29e30 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
29e40 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  nt.)^.**.** [[SQ
29e50 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
29e60 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74  ER_DEPTH]] ^(<dt
29e70 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52  >SQLITE_LIMIT_TR
29e80 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e  IGGER_DEPTH</dt>
29e90 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
29ea0 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63  mum depth of rec
29eb0 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67  ursion for trigg
29ec0 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ers.</dd>)^.**.*
29ed0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
29ee0 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 5d  _WORKER_THREADS]
29ef0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
29f00 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45  IMIT_WORKER_THRE
29f10 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ADS</dt>.** <dd>
29f20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
29f30 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79 20  er of auxiliary 
29f40 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20 74  worker threads t
29f50 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20  hat a single.** 
29f60 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
29f70 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c  ent] may start.<
29f80 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
29f90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
29fa0 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20  E_LIMIT_LENGTH  
29fb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
29fc0 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
29fd0 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
29fe0 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
29ff0 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
2a000 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
2a010 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a020 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
2a030 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
2a040 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
2a050 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
2a060 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
2a070 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20  OUND_SELECT     
2a080 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
2a090 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
2a0a0 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20  E_OP            
2a0b0 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
2a0c0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55   SQLITE_LIMIT_FU
2a0d0 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20  NCTION_ARG      
2a0e0 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
2a0f0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  e SQLITE_LIMIT_A
2a100 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20  TTACHED         
2a110 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69           7.#defi
2a120 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2a130 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
2a140 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66  GTH       8.#def
2a150 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2a160 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
2a170 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65             9.#de
2a180 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2a190 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20  T_TRIGGER_DEPTH 
2a1a0 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64             10.#d
2a1b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2a1c0 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44  IT_WORKER_THREAD
2a1d0 53 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a  S           11..
2a1e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2a1f0 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c  Compiling An SQL
2a200 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45   Statement.** KE
2a210 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61  YWORDS: {SQL sta
2a220 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d  tement compiler}
2a230 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2a240 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54  te3.** CONSTRUCT
2a250 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OR: sqlite3_stmt
2a260 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74  .**.** To execut
2a270 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20  e an SQL query, 
2a280 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65  it must first be
2a290 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61   compiled into a
2a2a0 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72   byte-code.** pr
2a2b0 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20  ogram using one 
2a2c0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
2a2d0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
2a2e0 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62  st argument, "db
2a2f0 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73  ", is a [databas
2a300 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62  e connection] ob
2a310 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a  tained from a.**
2a320 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
2a330 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
2a340 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
2a350 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
2a360 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  or.** [sqlite3_o
2a370 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64  pen16()].  The d
2a380 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2a390 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65  on must not have
2a3a0 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a   been closed..**
2a3b0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
2a3c0 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c  rgument, "zSql",
2a3d0 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   is the statemen
2a3e0 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
2a3f0 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20  , encoded.** as 
2a400 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
2a410 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c  UTF-16.  The sql
2a420 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61  ite3_prepare() a
2a430 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
2a440 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72  re_v2().** inter
2a450 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c  faces use UTF-8,
2a460 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
2a470 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c  pare16() and sql
2a480 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2a490 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31  2().** use UTF-1
2a4a0 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  6..**.** ^If the
2a4b0 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20   nByte argument 
2a4c0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
2a4d0 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75  n zSql is read u
2a4e0 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73  p to the.** firs
2a4f0 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
2a500 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20  r. ^If nByte is 
2a510 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 69  positive, then i
2a520 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  t is the.** numb
2a530 65 72 20 6f 66 20 62 79 74 65 73 20 72 65 61 64  er of bytes read
2a540 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66   from zSql.  ^If
2a550 20 6e 42 79 74 65 20 69 73 20 7a 65 72 6f 2c 20   nByte is zero, 
2a560 74 68 65 6e 20 6e 6f 20 70 72 65 70 61 72 65 64  then no prepared
2a570 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 73  .** statement is
2a580 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49   generated..** I
2a590 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f  f the caller kno
2a5a0 77 73 20 74 68 61 74 20 74 68 65 20 73 75 70 70  ws that the supp
2a5b0 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e  lied string is n
2a5c0 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74  ul-terminated, t
2a5d0 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73 20  hen.** there is 
2a5e0 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61  a small performa
2a5f0 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f  nce advantage to
2a600 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74   passing an nByt
2a610 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
2a620 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65  .** is the numbe
2a630 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2a640 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c  e input string <
2a650 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a  i>including</i>.
2a660 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69  ** the nul-termi
2a670 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  nator..**.** ^If
2a680 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e   pzTail is not N
2a690 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c  ULL then *pzTail
2a6a0 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
2a6b0 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62  t to the first b
2a6c0 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20  yte.** past the 
2a6d0 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74  end of the first
2a6e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
2a6f0 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72  n zSql.  These r
2a700 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20  outines only.** 
2a710 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73  compile the firs
2a720 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  t statement in z
2a730 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20  Sql, so *pzTail 
2a740 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
2a750 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61   to.** what rema
2a760 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a  ins uncompiled..
2a770 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69  **.** ^*ppStmt i
2a780 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
2a790 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70  to a compiled [p
2a7a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2a7b0 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a  t] that can be.*
2a7c0 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67  * executed using
2a7d0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2a7e0 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73  ].  ^If there is
2a7f0 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74   an error, *ppSt
2a800 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20  mt is set.** to 
2a810 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69  NULL.  ^If the i
2a820 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69  nput text contai
2a830 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68  ns no SQL (if th
2a840 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d  e input is an em
2a850 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72  pty.** string or
2a860 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e   a comment) then
2a870 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20   *ppStmt is set 
2a880 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20  to NULL..** The 
2a890 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72  calling procedur
2a8a0 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  e is responsible
2a8b0 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68   for deleting th
2a8c0 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51  e compiled.** SQ
2a8d0 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  L statement usin
2a8e0 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
2a8f0 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20  ize()] after it 
2a900 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
2a910 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20  h it..** ppStmt 
2a920 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e  may not be NULL.
2a930 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65  .**.** ^On succe
2a940 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ss, the sqlite3_
2a950 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79  prepare() family
2a960 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74   of routines ret
2a970 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b  urn [SQLITE_OK];
2a980 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e  .** otherwise an
2a990 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
2a9a0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2a9b0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
2a9c0 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71  pare_v2() and sq
2a9d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2a9e0 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20  v2() interfaces 
2a9f0 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64  are.** recommend
2aa00 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70  ed for all new p
2aa10 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f  rograms. The two
2aa20 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65   older interface
2aa30 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a  s are retained.*
2aa40 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  * for backwards 
2aa50 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62  compatibility, b
2aa60 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20  ut their use is 
2aa70 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20  discouraged..** 
2aa80 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74  ^In the "v2" int
2aa90 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65  erfaces, the pre
2aaa0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
2aab0 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72  ** that is retur
2aac0 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ned (the [sqlite
2aad0 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20  3_stmt] object) 
2aae0 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20  contains a copy 
2aaf0 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e  of the.** origin
2ab00 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69  al SQL text. Thi
2ab10 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71  s causes the [sq
2ab20 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e  lite3_step()] in
2ab30 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65  terface to.** be
2ab40 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79  have differently
2ab50 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a   in three ways:.
2ab60 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
2ab70 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  i>.** ^If the da
2ab80 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
2ab90 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f  anges, instead o
2aba0 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  f returning [SQL
2abb0 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69  ITE_SCHEMA] as i
2abc0 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64  t.** always used
2abd0 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33   to do, [sqlite3
2abe0 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75  _step()] will au
2abf0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
2ac00 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a  mpile the SQL.**
2ac10 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
2ac20 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61  ry to run it aga
2ac30 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b  in. As many as [
2ac40 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d  SQLITE_MAX_SCHEM
2ac50 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72  A_RETRY].** retr
2ac60 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62  ies will occur b
2ac70 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74  efore sqlite3_st
2ac80 65 70 28 29 20 67 69 76 65 73 20 75 70 20 61 6e  ep() gives up an
2ac90 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72  d returns an err
2aca0 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  or..** </li>.**.
2acb0 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e  ** <li>.** ^When
2acc0 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
2acd0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
2ace0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f  )] will return o
2acf0 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c  ne of the detail
2ad00 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  ed.** [error cod
2ad10 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  es] or [extended
2ad20 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20   error codes].  
2ad30 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61  ^The legacy beha
2ad40 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a  vior was that.**
2ad50 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2ad60 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74  ] would only ret
2ad70 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53  urn a generic [S
2ad80 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73  QLITE_ERROR] res
2ad90 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20  ult code.** and 
2ada0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2adb0 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61  would have to ma
2adc0 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c  ke a second call
2add0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
2ade0 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65  et()].** in orde
2adf0 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e  r to find the un
2ae00 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f  derlying cause o
2ae10 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57  f the problem. W
2ae20 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65  ith the "v2" pre
2ae30 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  pare.** interfac
2ae40 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69  es, the underlyi
2ae50 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68  ng reason for th
2ae60 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  e error is retur
2ae70 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  ned immediately.
2ae80 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
2ae90 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  <li>.** ^If the 
2aea0 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62  specific value b
2aeb0 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74  ound to [paramet
2aec0 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65  er | host parame
2aed0 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20  ter] in the .** 
2aee0 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67  WHERE clause mig
2aef0 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65  ht influence the
2af00 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79   choice of query
2af10 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74   plan for a stat
2af20 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74  ement,.** then t
2af30 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c  he statement wil
2af40 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  l be automatical
2af50 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61  ly recompiled, a
2af60 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62  s if there had b
2af70 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61  een .** a schema
2af80 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20   change, on the 
2af90 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f  first  [sqlite3_
2afa0 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c  step()] call fol
2afb0 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67  lowing any chang
2afc0 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  e.** to the [sql
2afd0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c  ite3_bind_text |
2afe0 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68   bindings] of th
2aff0 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20  at [parameter]. 
2b000 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69  .** ^The specifi
2b010 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45  c value of WHERE
2b020 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74  -clause [paramet
2b030 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65  er] might influe
2b040 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69  nce the .** choi
2b050 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e  ce of query plan
2b060 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
2b070 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61  r is the left-ha
2b080 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49  nd side of a [LI
2b090 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d  KE].** or [GLOB]
2b0a0 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20   operator or if 
2b0b0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
2b0c0 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20   compared to an 
2b0d0 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a  indexed column.*
2b0e0 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54  * and the [SQLIT
2b0f0 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20  E_ENABLE_STAT3] 
2b100 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
2b110 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a  ion is enabled..
2b120 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c  ** </li>.** </ol
2b130 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  >.*/.SQLITE_API 
2b140 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
2b150 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  LL sqlite3_prepa
2b160 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  re(.  sqlite3 *d
2b170 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
2b180 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
2b190 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2b1a0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
2b1b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
2b1c0 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
2b1d0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
2b1e0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
2b1f0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
2b200 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
2b210 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
2b220 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
2b230 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
2b240 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2b250 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
2b260 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
2b270 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
2b280 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
2b290 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2b2a0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
2b2b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2b2c0 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
2b2d0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
2b2e0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
2b2f0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2b300 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
2b310 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
2b320 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
2b330 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
2b340 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
2b350 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
2b360 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
2b370 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
2b380 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
2b390 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
2b3a0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2b3b0 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
2b3c0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
2b3d0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
2b3e0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
2b3f0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2b400 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
2b410 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2b420 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
2b430 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
2b440 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
2b450 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2b460 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
2b470 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
2b480 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
2b490 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
2b4a0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
2b4b0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
2b4c0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
2b4d0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
2b4e0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
2b4f0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
2b500 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2b510 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
2b520 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
2b530 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
2b540 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
2b550 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2b560 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
2b570 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2b580 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  6_v2(.  sqlite3 
2b590 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2b5a0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
2b5b0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
2b5c0 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
2b5d0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
2b5e0 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
2b5f0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
2b600 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2b610 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
2b620 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
2b630 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
2b640 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
2b650 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
2b660 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2b670 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
2b680 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
2b690 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
2b6a0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
2b6b0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
2b6c0 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67  3REF: Retrieving
2b6d0 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a   Statement SQL.*
2b6e0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2b6f0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
2b700 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  is interface can
2b710 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72   be used to retr
2b720 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70  ieve a saved cop
2b730 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61  y of the origina
2b740 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73  l.** SQL text us
2b750 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b  ed to create a [
2b760 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b770 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74  nt] if that stat
2b780 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d  ement was.** com
2b790 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68  piled using eith
2b7a0 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
2b7b0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
2b7c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2b7d0 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  v2()]..*/.SQLITE
2b7e0 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
2b7f0 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
2b800 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69  sqlite3_sql(sqli
2b810 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2b820 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2b830 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
2b840 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
2b850 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61   Writes The Data
2b860 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  base.** METHOD: 
2b870 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2b880 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2b890 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29  stmt_readonly(X)
2b8a0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2b8b0 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
2b8c0 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c  o) if.** and onl
2b8d0 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72  y if the [prepar
2b8e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20  ed statement] X 
2b8f0 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20  makes no direct 
2b900 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68  changes to.** th
2b910 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
2b920 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a   database file..
2b930 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
2b940 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
2b950 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2b960 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75  ns] or.** [virtu
2b970 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74  al tables] might
2b980 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
2b990 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20  base indirectly 
2b9a0 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74  as a side effect
2b9b0 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .  .** ^(For exa
2b9c0 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c  mple, if an appl
2b9d0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20  ication defines 
2b9e0 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c  a function "eval
2b9f0 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c  ()" that .** cal
2ba00 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ls [sqlite3_exec
2ba10 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f  ()], then the fo
2ba20 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74  llowing SQL stat
2ba30 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63  ement would.** c
2ba40 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
2ba50 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20  se file through 
2ba60 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a  side-effects:.**
2ba70 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
2ba80 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45  <pre>.**    SELE
2ba90 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20  CT eval('DELETE 
2baa0 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74  FROM t1') FROM t
2bab0 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  2;.** </pre></bl
2bac0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
2bad0 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20  But because the 
2bae0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2baf0 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nt does not chan
2bb00 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
2bb10 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79  file.** directly
2bb20 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  , sqlite3_stmt_r
2bb30 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20  eadonly() would 
2bb40 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75  still return tru
2bb50 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e  e.)^.**.** ^Tran
2bb60 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20  saction control 
2bb70 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20  statements such 
2bb80 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d  as [BEGIN], [COM
2bb90 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d  MIT], [ROLLBACK]
2bba0 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d  ,.** [SAVEPOINT]
2bbb0 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20  , and [RELEASE] 
2bbc0 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74  cause sqlite3_st
2bbd0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
2bbe0 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a   return true,.**
2bbf0 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65   since the state
2bc00 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73  ments themselves
2bc10 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79   do not actually
2bc20 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
2bc30 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68  base but.** rath
2bc40 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20  er they control 
2bc50 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68  the timing of wh
2bc60 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65  en other stateme
2bc70 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a  nts modify the .
2bc80 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54  ** database.  ^T
2bc90 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20  he [ATTACH] and 
2bca0 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65  [DETACH] stateme
2bcb0 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a  nts also cause.*
2bcc0 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  * sqlite3_stmt_r
2bcd0 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74  eadonly() to ret
2bce0 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20  urn true since, 
2bcf0 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74  while those stat
2bd00 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65  ements.** change
2bd10 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
2bd20 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65  on of a database
2bd30 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65   connection, the
2bd40 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a  y do not make .*
2bd50 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  * changes to the
2bd60 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
2bd70 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f  database files o
2bd80 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 53 51 4c 49 54  n disk..*/.SQLIT
2bd90 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
2bda0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2bdb0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73  _stmt_readonly(s
2bdc0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2bdd0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
2bde0 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
2bdf0 49 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74  If A Prepared St
2be00 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e  atement Has Been
2be10 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44   Reset.** METHOD
2be20 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2be30 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2be40 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69  3_stmt_busy(S) i
2be50 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2be60 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29   true (non-zero)
2be70 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   if the.** [prep
2be80 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2be90 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 70 70  S has been stepp
2bea0 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65  ed at least once
2beb0 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69   using .** [sqli
2bec0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74  te3_step(S)] but
2bed0 20 68 61 73 20 6e 65 69 74 68 65 72 20 72 75 6e   has neither run
2bee0 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 28   to completion (
2bef0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c  returned.** [SQL
2bf00 49 54 45 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b  ITE_DONE] from [
2bf10 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
2bf20 29 20 6e 6f 72 0a 2a 2a 20 62 65 65 6e 20 72 65  ) nor.** been re
2bf30 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  set using [sqlit
2bf40 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e  e3_reset(S)].  ^
2bf50 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
2bf60 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65  _busy(S).** inte
2bf70 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 66 61  rface returns fa
2bf80 6c 73 65 20 69 66 20 53 20 69 73 20 61 20 4e 55  lse if S is a NU
2bf90 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20  LL pointer.  If 
2bfa0 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e  S is not a .** N
2bfb0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  ULL pointer and 
2bfc0 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72  is not a pointer
2bfd0 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65   to a valid [pre
2bfe0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2bff0 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e  .** object, then
2c000 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
2c010 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
2c020 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61  robably undesira
2c030 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ble..**.** This 
2c040 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
2c050 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61   used in combina
2c060 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65  tion [sqlite3_ne
2c070 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f  xt_stmt()].** to
2c080 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70   locate all prep
2c090 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20  ared statements 
2c0a0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2c0b0 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63  a database .** c
2c0c0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61  onnection that a
2c0d0 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65  re in need of be
2c0e0 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69 73  ing reset.  This
2c0f0 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a   can be used,.**
2c100 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e   for example, in
2c110 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74   diagnostic rout
2c120 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20 66  ines to search f
2c130 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20  or prepared .** 
2c140 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20  statements that 
2c150 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72  are holding a tr
2c160 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a  ansaction open..
2c170 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
2c180 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
2c190 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
2c1a0 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  sy(sqlite3_stmt*
2c1b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2c1c0 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20  EF: Dynamically 
2c1d0 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65  Typed Value Obje
2c1e0 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
2c1f0 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  {protected sqlit
2c200 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f  e3_value} {unpro
2c210 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2c220 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  alue}.**.** SQLi
2c230 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69  te uses the sqli
2c240 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2c250 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c   to represent al
2c260 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74  l values.** that
2c270 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69   can be stored i
2c280 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  n a database tab
2c290 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20  le. SQLite uses 
2c2a0 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a  dynamic typing.*
2c2b0 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73  * for the values
2c2c0 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61   it stores.  ^Va
2c2d0 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73  lues stored in s
2c2e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2c2f0 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69  ects.** can be i
2c300 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e  ntegers, floatin
2c310 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20  g point values, 
2c320 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20  strings, BLOBs, 
2c330 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41  or NULL..**.** A
2c340 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  n sqlite3_value 
2c350 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69  object may be ei
2c360 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22  ther "protected"
2c370 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64   or "unprotected
2c380 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72  "..** Some inter
2c390 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20  faces require a 
2c3a0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2c3b0 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20  3_value.  Other 
2c3c0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69  interfaces.** wi
2c3d0 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72  ll accept either
2c3e0 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20   a protected or 
2c3f0 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  an unprotected s
2c400 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
2c410 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65   Every interface
2c420 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71   that accepts sq
2c430 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75  lite3_value argu
2c440 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a  ments specifies.
2c450 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** whether or no
2c460 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20  t it requires a 
2c470 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2c480 33 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a  3_value.  The.**
2c490 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2c4a0 64 75 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65  dup()] interface
2c4b0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
2c4c0 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65 77 20  construct a new 
2c4d0 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64 20 73 71  .** protected sq
2c4e0 6c 69 74 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d  lite3_value from
2c4f0 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   an unprotected 
2c500 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
2c510 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22  *.** The terms "
2c520 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22  protected" and "
2c530 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66  unprotected" ref
2c540 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72  er to whether or
2c550 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20   not.** a mutex 
2c560 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74  is held.  An int
2c570 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68  ernal mutex is h
2c580 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63  eld for a protec
2c590 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
2c5a0 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20  alue object but 
2c5b0 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  no mutex is held
2c5c0 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63   for an unprotec
2c5d0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
2c5e0 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66  alue object.  If
2c5f0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
2c600 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65  led to be single
2c610 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69  -threaded.** (wi
2c620 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  th [SQLITE_THREA
2c630 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74  DSAFE=0] and wit
2c640 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61  h [sqlite3_threa
2c650 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69  dsafe()] returni
2c660 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53  ng 0).** or if S
2c670 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20  QLite is run in 
2c680 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d  one of reduced m
2c690 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b  utex modes .** [
2c6a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
2c6b0 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b  NGLETHREAD] or [
2c6c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
2c6d0 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68  LTITHREAD].** th
2c6e0 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64  en there is no d
2c6f0 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
2c700 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
2c710 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
2c720 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2c730 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63  jects and they c
2c740 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72  an be used inter
2c750 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77  changeably.  How
2c760 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78  ever,.** for max
2c770 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62  imum code portab
2c780 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f  ility it is reco
2c790 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
2c7a0 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69  lications.** sti
2c7b0 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  ll make the dist
2c7c0 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
2c7d0 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
2c7e0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
2c7f0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2c800 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74  ts even when not
2c810 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72   strictly requir
2c820 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
2c830 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2c840 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61  ects that are pa
2c850 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65  ssed as paramete
2c860 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69  rs into the.** i
2c870 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2c880 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
2c890 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2c8a0 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74  ons] are protect
2c8b0 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ed..** ^The sqli
2c8c0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2c8d0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
2c8e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2c8f0 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72  value()] is unpr
2c900 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72  otected..** Unpr
2c910 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2c920 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61  value objects ma
2c930 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
2c940 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ith.** [sqlite3_
2c950 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20  result_value()] 
2c960 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
2c970 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54  d_value()]..** T
2c980 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2c990 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  e_blob | sqlite3
2c9a0 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66  _value_type()] f
2c9b0 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65  amily of.** inte
2c9c0 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70  rfaces require p
2c9d0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2c9e0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a  _value objects..
2c9f0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
2ca00 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61  t Mem sqlite3_va
2ca10 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lue;../*.** CAPI
2ca20 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69  3REF: SQL Functi
2ca30 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63  on Context Objec
2ca40 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74  t.**.** The cont
2ca50 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20  ext in which an 
2ca60 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65  SQL function exe
2ca70 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20  cutes is stored 
2ca80 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  in an.** sqlite3
2ca90 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e  _context object.
2caa0 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20    ^A pointer to 
2cab0 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  an sqlite3_conte
2cac0 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20  xt object.** is 
2cad0 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72  always first par
2cae0 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69  ameter to [appli
2caf0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2cb00 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  QL functions]..*
2cb10 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
2cb20 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2cb30 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
2cb40 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20  ation will pass 
2cb50 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  this.** pointer 
2cb60 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c  through into cal
2cb70 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ls to [sqlite3_r
2cb80 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69  esult_int | sqli
2cb90 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a  te3_result()],.*
2cba0 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65  * [sqlite3_aggre
2cbb0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c  gate_context()],
2cbc0 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
2cbd0 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ata()],.** [sqli
2cbe0 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
2cbf0 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74  andle()], [sqlit
2cc00 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
2cc10 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71  ],.** and/or [sq
2cc20 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
2cc30 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  a()]..*/.typedef
2cc40 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
2cc50 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f  context sqlite3_
2cc60 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20  context;../*.** 
2cc70 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e  CAPI3REF: Bindin
2cc80 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70  g Values To Prep
2cc90 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a  ared Statements.
2cca0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f  ** KEYWORDS: {ho
2ccb0 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68  st parameter} {h
2ccc0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20  ost parameters} 
2ccd0 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  {host parameter 
2cce0 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  name}.** KEYWORD
2ccf0 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  S: {SQL paramete
2cd00 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  r} {SQL paramete
2cd10 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62  rs} {parameter b
2cd20 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f  inding}.** METHO
2cd30 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2cd40 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53  **.** ^(In the S
2cd50 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
2cd60 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  t input to [sqli
2cd70 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2cd80 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e  ] and its varian
2cd90 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20  ts,.** literals 
2cda0 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20  may be replaced 
2cdb0 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d  by a [parameter]
2cdc0 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e   that matches on
2cdd0 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a  e of following.*
2cde0 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a  * templates:.**.
2cdf0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
2ce00 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e   ?.** <li>  ?NNN
2ce10 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a  .** <li>  :VVV.*
2ce20 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20  * <li>  @VVV.** 
2ce30 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f  <li>  $VVV.** </
2ce40 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  ul>.**.** In the
2ce50 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65   templates above
2ce60 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73  , NNN represents
2ce70 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65   an integer lite
2ce80 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20  ral,.** and VVV 
2ce90 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c  represents an al
2cea0 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74  phanumeric ident
2ceb0 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76  ifier.)^  ^The v
2cec0 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a  alues of these.*
2ced0 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c  * parameters (al
2cee0 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20  so called "host 
2cef0 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22  parameter names"
2cf00 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74   or "SQL paramet
2cf10 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20  ers").** can be 
2cf20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71  set using the sq
2cf30 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
2cf40 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20  outines defined 
2cf50 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  here..**.** ^The
2cf60 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
2cf70 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  to the sqlite3_b
2cf80 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
2cf90 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20   is always.** a 
2cfa0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
2cfb0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
2cfc0 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72  ject returned fr
2cfd0 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  om.** [sqlite3_p
2cfe0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2cff0 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a  its variants..**
2d000 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
2d010 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
2d020 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c  index of the SQL
2d030 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65   parameter to be
2d040 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65   set..** ^The le
2d050 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d  ftmost SQL param
2d060 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
2d070 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74  x of 1.  ^When t
2d080 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a  he same named.**
2d090 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
2d0a0 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e  s used more than
2d0b0 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e   once, second an
2d0c0 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  d subsequent.** 
2d0d0 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65  occurrences have
2d0e0 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20   the same index 
2d0f0 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63  as the first occ
2d100 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65  urrence..** ^The
2d110 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64   index for named
2d120 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20   parameters can 
2d130 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69  be looked up usi
2d140 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
2d150 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2d160 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69  r_index()] API i
2d170 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65  f desired.  ^The
2d180 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f   index.** for "?
2d190 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20  NNN" parameters 
2d1a0 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
2d1b0 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e  NNN..** ^The NNN
2d1c0 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62   value must be b
2d1d0 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65  etween 1 and the
2d1e0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
2d1f0 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  )].** parameter 
2d200 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
2d210 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28  RIABLE_NUMBER] (
2d220 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39  default value: 9
2d230 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  99)..**.** ^The 
2d240 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
2d250 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62  s the value to b
2d260 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d  ind to the param
2d270 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  eter..** ^If the
2d280 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
2d290 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
2d2a0 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
2d2b0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
2d2c0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  .** or sqlite3_b
2d2d0 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20  ind_blob() is a 
2d2e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
2d2f0 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  n the fourth par
2d300 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e  ameter.** is ign
2d310 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64  ored and the end
2d320 20 72 65 73 75 6c 74 20 69 73 20 74 68 65 20 73   result is the s
2d330 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62  ame as sqlite3_b
2d340 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a  ind_null()..**.*
2d350 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75  * ^(In those rou
2d360 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20  tines that have 
2d370 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  a fourth argumen
2d380 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20  t, its value is 
2d390 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
2d3a0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61   bytes in the pa
2d3b0 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20  rameter.  To be 
2d3c0 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65  clear: the value
2d3d0 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
2d3e0 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75  r of <u>bytes</u
2d3f0 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20  > in the value, 
2d400 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
2d410 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a  f characters.)^.
2d420 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74  ** ^If the fourt
2d430 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
2d440 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2d450 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  () or sqlite3_bi
2d460 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69  nd_text16().** i
2d470 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
2d480 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74   the length of t
2d490 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  he string is.** 
2d4a0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2d4b0 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69  tes up to the fi
2d4c0 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
2d4d0 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66  tor..** If the f
2d4e0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
2d4f0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2d500 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69  blob() is negati
2d510 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ve, then.** the 
2d520 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
2d530 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e  fined..** If a n
2d540 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72  on-negative four
2d550 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
2d560 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69  provided to sqli
2d570 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a  te3_bind_text().
2d580 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ** or sqlite3_bi
2d590 6e 64 5f 74 65 78 74 31 36 28 29 20 6f 72 20 73  nd_text16() or s
2d5a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2d5b0 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61  64() then.** tha
2d5c0 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  t parameter must
2d5d0 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66   be the byte off
2d5e0 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65  set.** where the
2d5f0 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20   NUL terminator 
2d600 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75  would occur assu
2d610 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20  ming the string 
2d620 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d  were NUL.** term
2d630 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20  inated.  If any 
2d640 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f  NUL characters o
2d650 63 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66  ccur at byte off
2d660 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a  sets less than .
2d670 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ** the value of 
2d680 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
2d690 65 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65  eter then the re
2d6a0 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76  sulting string v
2d6b0 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  alue will.** con
2d6c0 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55  tain embedded NU
2d6d0 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  Ls.  The result 
2d6e0 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69  of expressions i
2d6f0 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73  nvolving strings
2d700 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65  .** with embedde
2d710 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69  d NULs is undefi
2d720 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2d730 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74  fifth argument t
2d740 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e 64 20 73  o the BLOB and s
2d750 74 72 69 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e  tring binding in
2d760 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 61  terfaces.** is a
2d770 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64   destructor used
2d780 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
2d790 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74  he BLOB or.** st
2d7a0 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74  ring after SQLit
2d7b0 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  e has finished w
2d7c0 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65  ith it.  ^The de
2d7d0 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c  structor is call
2d7e0 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65  ed.** to dispose
2d7f0 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20   of the BLOB or 
2d800 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74  string even if t
2d810 68 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20  he call to bind 
2d820 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49  API fails..** ^I
2d830 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
2d840 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73  ment is.** the s
2d850 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51  pecial value [SQ
2d860 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68  LITE_STATIC], th
2d870 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65  en SQLite assume
2d880 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e  s that the.** in
2d890 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20  formation is in 
2d8a0 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65  static, unmanage
2d8b0 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  d space and does
2d8c0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
2d8d0 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  freed..** ^If th
2d8e0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
2d8f0 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b   has the value [
2d900 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
2d910 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  ], then.** SQLit
2d920 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20  e makes its own 
2d930 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
2d940 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61  the data immedia
2d950 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20  tely, before.** 
2d960 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
2d970 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  _*() routine ret
2d980 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  urns..**.** ^The
2d990 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20   sixth argument 
2d9a0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2d9b0 74 65 78 74 36 34 28 29 20 6d 75 73 74 20 62 65  text64() must be
2d9c0 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49   one of.** [SQLI
2d9d0 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54  TE_UTF8], [SQLIT
2d9e0 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54  E_UTF16], [SQLIT
2d9f0 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b  E_UTF16BE], or [
2da00 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a  SQLITE_UTF16LE].
2da10 2a 2a 20 74 6f 20 73 70 65 63 69 66 79 20 74 68  ** to specify th
2da20 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68  e encoding of th
2da30 65 20 74 65 78 74 20 69 6e 20 74 68 65 20 74 68  e text in the th
2da40 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ird parameter.  
2da50 49 66 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 20  If.** the sixth 
2da60 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
2da70 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28  te3_bind_text64(
2da80 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20  ) is not one of 
2da90 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76  the.** allowed v
2daa0 61 6c 75 65 73 20 73 68 6f 77 6e 20 61 62 6f 76  alues shown abov
2dab0 65 2c 20 6f 72 20 69 66 20 74 68 65 20 74 65 78  e, or if the tex
2dac0 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69  t encoding is di
2dad0 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20  fferent.** from 
2dae0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65  the encoding spe
2daf0 63 69 66 69 65 64 20 62 79 20 74 68 65 20 73 69  cified by the si
2db00 78 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 74  xth parameter, t
2db10 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
2db20 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64  .** is undefined
2db30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2db40 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
2db50 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e  ob() routine bin
2db60 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e  ds a BLOB of len
2db70 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73  gth N that.** is
2db80 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72   filled with zer
2db90 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f  oes.  ^A zeroblo
2dba0 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61  b uses a fixed a
2dbb0 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a  mount of memory.
2dbc0 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65  ** (just an inte
2dbd0 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20  ger to hold its 
2dbe0 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69  size) while it i
2dbf0 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65  s being processe
2dc00 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20  d..** Zeroblobs 
2dc10 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20  are intended to 
2dc20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f  serve as placeho
2dc30 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20  lders for BLOBs 
2dc40 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  whose.** content
2dc50 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65   is later writte
2dc60 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
2dc70 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20  te3_blob_open | 
2dc80 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42  incremental BLOB
2dc90 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a   I/O] routines..
2dca0 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76  ** ^A negative v
2dcb0 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72  alue for the zer
2dcc0 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e  oblob results in
2dcd0 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
2dce0 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  LOB..**.** ^If a
2dcf0 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ny of the sqlite
2dd00 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
2dd10 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77  nes are called w
2dd20 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
2dd30 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70  er.** for the [p
2dd40 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2dd50 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65  t] or with a pre
2dd60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2dd70 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71  for which.** [sq
2dd80 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
2dd90 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f  s been called mo
2dda0 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e  re recently than
2ddb0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2ddc0 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  )],.** then the 
2ddd0 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e  call will return
2dde0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2ddf0 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65  .  If any sqlite
2de00 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75  3_bind_().** rou
2de10 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61  tine is passed a
2de20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2de30 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62  ment] that has b
2de40 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74  een finalized, t
2de50 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20  he.** result is 
2de60 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
2de70 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a  obably harmful..
2de80 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20  **.** ^Bindings 
2de90 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20  are not cleared 
2dea0 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
2deb0 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65  reset()] routine
2dec0 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61  ..** ^Unbound pa
2ded0 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74  rameters are int
2dee0 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c  erpreted as NULL
2def0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2df00 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74  ite3_bind_* rout
2df10 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c  ines return [SQL
2df20 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
2df30 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72  ss or an.** [err
2df40 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74  or code] if anyt
2df50 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e  hing goes wrong.
2df60 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f  .** ^[SQLITE_TOO
2df70 42 49 47 5d 20 6d 69 67 68 74 20 62 65 20 72 65  BIG] might be re
2df80 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 73 69  turned if the si
2df90 7a 65 20 6f 66 20 61 20 73 74 72 69 6e 67 20 6f  ze of a string o
2dfa0 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64  r BLOB.** exceed
2dfb0 73 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 64  s limits imposed
2dfc0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d   by [sqlite3_lim
2dfd0 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  it]([SQLITE_LIMI
2dfe0 54 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a  T_LENGTH]) or.**
2dff0 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e   [SQLITE_MAX_LEN
2e000 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54  GTH]..** ^[SQLIT
2e010 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75  E_RANGE] is retu
2e020 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61  rned if the para
2e030 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69  meter.** index i
2e040 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20  s out of range. 
2e050 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d   ^[SQLITE_NOMEM]
2e060 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
2e070 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a  malloc() fails..
2e080 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2e090 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2e0a0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
2e0b0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
2e0c0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
2e0d0 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
2e0e0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2e0f0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53  r_index()]..*/.S
2e100 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
2e110 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2e120 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73  ite3_bind_blob(s
2e130 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2e140 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
2e150 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76  int n, void(*)(v
2e160 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41  oid*));.SQLITE_A
2e170 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
2e180 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69  DCALL sqlite3_bi
2e190 6e 64 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65  nd_blob64(sqlite
2e1a0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
2e1b0 6e 73 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74  nst void*, sqlit
2e1c0 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20  e3_uint64,.     
2e1d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e1e0 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a     void(*)(void*
2e1f0 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  ));.SQLITE_API i
2e200 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
2e210 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64  L sqlite3_bind_d
2e220 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
2e230 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65  mt*, int, double
2e240 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2e250 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
2e260 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
2e270 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
2e280 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 53 51 4c 49   int, int);.SQLI
2e290 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
2e2a0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
2e2b0 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c  3_bind_int64(sql
2e2c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2e2d0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
2e2e0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2e2f0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2e300 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
2e310 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2e320 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
2e330 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
2e340 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  ALL sqlite3_bind
2e350 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
2e360 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  mt*,int,const ch
2e370 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a 29 28  ar*,int,void(*)(
2e380 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f  void*));.SQLITE_
2e390 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
2e3a0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62  TDCALL sqlite3_b
2e3b0 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ind_text16(sqlit
2e3c0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
2e3d0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
2e3e0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
2e3f0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2e400 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
2e410 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2e420 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
2e430 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68  *, int, const ch
2e440 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e  ar*, sqlite3_uin
2e450 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20  t64,.           
2e460 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
2e470 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e  id(*)(void*), un
2e480 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f  signed char enco
2e490 64 69 6e 67 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ding);.SQLITE_AP
2e4a0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
2e4b0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e  CALL sqlite3_bin
2e4c0 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  d_value(sqlite3_
2e4d0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
2e4e0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t sqlite3_value*
2e4f0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2e500 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
2e510 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
2e520 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  roblob(sqlite3_s
2e530 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e  tmt*, int, int n
2e540 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2e550 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
2e560 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
2e570 72 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33  roblob64(sqlite3
2e580 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c  _stmt*, int, sql
2e590 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 0a 2f  ite3_uint64);../
2e5a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
2e5b0 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72  umber Of SQL Par
2e5c0 61 6d 65 74 65 72 73 0a 2a 2a 20 4d 45 54 48 4f  ameters.** METHO
2e5d0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2e5e0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
2e5f0 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ine can be used 
2e600 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62  to find the numb
2e610 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d  er of [SQL param
2e620 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b  eters].** in a [
2e630 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2e640 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65  nt].  SQL parame
2e650 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20  ters are tokens 
2e660 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22  of the.** form "
2e670 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41  ?", "?NNN", ":AA
2e680 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22  A", "$AAA", or "
2e690 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65  @AAA" that serve
2e6a0 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64   as.** placehold
2e6b0 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74  ers for values t
2e6c0 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33  hat are [sqlite3
2e6d0 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75  _bind_blob | bou
2e6e0 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61  nd].** to the pa
2e6f0 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61  rameters at a la
2e700 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  ter time..**.** 
2e710 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61  ^(This routine a
2e720 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20  ctually returns 
2e730 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
2e740 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d   largest (rightm
2e750 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65  ost).** paramete
2e760 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73  r. For all forms
2e770 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68   except ?NNN, th
2e780 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f  is will correspo
2e790 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d  nd to the.** num
2e7a0 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61  ber of unique pa
2e7b0 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61  rameters.  If pa
2e7c0 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
2e7d0 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73  ?NNN form are us
2e7e0 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79  ed,.** there may
2e7f0 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20   be gaps in the 
2e800 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65  list.)^.**.** Se
2e810 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2e820 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
2e830 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
2e840 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2e850 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
2e860 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2e870 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2e880 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  ndex()]..*/.SQLI
2e890 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
2e8a0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
2e8b0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2e8c0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
2e8d0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
2e8e0 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20  PI3REF: Name Of 
2e8f0 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72  A Host Parameter
2e900 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2e910 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2e920 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
2e930 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
2e940 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72  P,N) interface r
2e950 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61  eturns.** the na
2e960 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b  me of the N-th [
2e970 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69  SQL parameter] i
2e980 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
2e990 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a  statement] P..**
2e9a0 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72   ^(SQL parameter
2e9b0 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
2e9c0 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
2e9d0 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
2e9e0 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d  A".** have a nam
2e9f0 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73  e which is the s
2ea00 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20  tring "?NNN" or 
2ea10 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
2ea20 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65   or "$AAA".** re
2ea30 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49  spectively..** I
2ea40 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
2ea50 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f  he initial ":" o
2ea60 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20  r "$" or "@" or 
2ea70 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64  "?".** is includ
2ea80 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
2ea90 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61  e name.)^.** ^Pa
2eaa0 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
2eab0 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74  form "?" without
2eac0 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74   a following int
2ead0 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d  eger have no nam
2eae0 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66  e.** and are ref
2eaf0 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d  erred to as "nam
2eb00 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79  eless" or "anony
2eb10 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22  mous parameters"
2eb20 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
2eb30 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  st host paramete
2eb40 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
2eb50 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a  f 1, not 0..**.*
2eb60 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20  * ^If the value 
2eb70 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
2eb80 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68  e or if the N-th
2eb90 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
2eba0 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20   nameless, then 
2ebb0 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64  NULL is returned
2ebc0 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  .  ^The returned
2ebd0 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c   string is.** al
2ebe0 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e  ways in UTF-8 en
2ebf0 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74  coding even if t
2ec00 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  he named paramet
2ec10 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e  er was.** origin
2ec20 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61  ally specified a
2ec30 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c  s UTF-16 in [sql
2ec40 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2ec50 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
2ec60 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2ec70 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2ec80 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
2ec90 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
2eca0 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
2ecb0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2ecc0 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
2ecd0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2ece0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2ecf0 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
2ed00 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51  I const char *SQ
2ed10 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2ed20 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2ed30 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ter_name(sqlite3
2ed40 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f  _stmt*, int);../
2ed50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
2ed60 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65  ndex Of A Parame
2ed70 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e  ter With A Given
2ed80 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a   Name.** METHOD:
2ed90 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2eda0 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
2edb0 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20  index of an SQL 
2edc0 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20  parameter given 
2edd0 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a  its name.  ^The.
2ede0 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72  ** index value r
2edf0 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61  eturned is suita
2ee00 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74  ble for use as t
2ee10 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72  he second.** par
2ee20 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
2ee30 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
2ee40 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e  ite3_bind()].  ^
2ee50 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74  A zero.** is ret
2ee60 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63  urned if no matc
2ee70 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69  hing parameter i
2ee80 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70  s found.  ^The p
2ee90 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65  arameter.** name
2eea0 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69   must be given i
2eeb0 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20  n UTF-8 even if 
2eec0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
2eed0 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72  tement.** was pr
2eee0 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d  epared from UTF-
2eef0 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73  16 text using [s
2ef00 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2ef10 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v2()]..**.** Se
2ef20 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2ef30 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
2ef40 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
2ef50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2ef60 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
2ef70 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2ef80 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2ef90 6e 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  name()]..*/.SQLI
2efa0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
2efb0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
2efc0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2efd0 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73  _index(sqlite3_s
2efe0 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  tmt*, const char
2eff0 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a   *zName);../*.**
2f000 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
2f010 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e   All Bindings On
2f020 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
2f030 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ement.** METHOD:
2f040 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2f050 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f  .** ^Contrary to
2f060 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f   the intuition o
2f070 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33  f many, [sqlite3
2f080 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e  _reset()] does n
2f090 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20  ot reset.** the 
2f0a0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2f0b0 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  ob | bindings] o
2f0c0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
2f0d0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73  atement]..** ^Us
2f0e0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74  e this routine t
2f0f0 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74  o reset all host
2f100 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e   parameters to N
2f110 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ULL..*/.SQLITE_A
2f120 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
2f130 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6c  DCALL sqlite3_cl
2f140 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  ear_bindings(sql
2f150 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
2f160 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
2f170 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20  mber Of Columns 
2f180 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a  In A Result Set.
2f190 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2f1a0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52  e3_stmt.**.** ^R
2f1b0 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72  eturn the number
2f1c0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
2f1d0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65  he result set re
2f1e0 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
2f1f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2f200 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75  ment]. ^This rou
2f210 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69  tine returns 0 i
2f220 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51  f pStmt is an SQ
2f230 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74  L.** statement t
2f240 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74  hat does not ret
2f250 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78  urn data (for ex
2f260 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45  ample an [UPDATE
2f270 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ])..**.** See al
2f280 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74  so: [sqlite3_dat
2f290 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51  a_count()].*/.SQ
2f2a0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
2f2b0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
2f2c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
2f2d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2f2e0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2f2f0 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e  PI3REF: Column N
2f300 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74  ames In A Result
2f310 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20   Set.** METHOD: 
2f320 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2f330 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
2f340 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  es return the na
2f350 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61  me assigned to a
2f360 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75   particular colu
2f370 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73  mn.** in the res
2f380 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
2f390 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
2f3a0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63    ^The sqlite3_c
2f3b0 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20  olumn_name().** 
2f3c0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2f3d0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
2f3e0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
2f3f0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a   UTF-8 string.**
2f400 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2f410 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74  umn_name16() ret
2f420 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2f430 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
2f440 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
2f450 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73  ring.  ^The firs
2f460 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
2f470 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2f480 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20  tement].** that 
2f490 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b  implements the [
2f4a0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
2f4b0 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  t. ^The second p
2f4c0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
2f4d0 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  ** column number
2f4e0 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  .  ^The leftmost
2f4f0 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65   column is numbe
2f500 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r 0..**.** ^The 
2f510 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
2f520 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64  pointer is valid
2f530 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68   until either th
2f540 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2f550 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73  ement].** is des
2f560 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74  troyed by [sqlit
2f570 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
2f580 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74  r until the stat
2f590 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74  ement is automat
2f5a0 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70  ically.** reprep
2f5b0 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ared by the firs
2f5c0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2f5d0 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61  e3_step()] for a
2f5e0 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a   particular run.
2f5f0 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  ** or until the 
2f600 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  next call to.** 
2f610 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2f620 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ame() or sqlite3
2f630 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
2f640 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c   on the same col
2f650 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73  umn..**.** ^If s
2f660 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
2f670 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65  fails during the
2f680 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65   processing of e
2f690 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a  ither routine.**
2f6a0 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75   (for example du
2f6b0 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f  ring a conversio
2f6c0 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20  n from UTF-8 to 
2f6d0 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a  UTF-16) then a.*
2f6e0 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
2f6f0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
2f700 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61  * ^The name of a
2f710 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
2f720 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
2f730 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66  he "AS" clause f
2f740 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d  or.** that colum
2f750 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61  n, if there is a
2f760 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66  n AS clause.  If
2f770 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20   there is no AS 
2f780 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74  clause.** then t
2f790 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63  he name of the c
2f7a0 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69  olumn is unspeci
2f7b0 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61  fied and may cha
2f7c0 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20  nge from.** one 
2f7d0 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
2f7e0 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a  e to the next..*
2f7f0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
2f800 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f  st char *SQLITE_
2f810 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
2f820 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69  column_name(sqli
2f830 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
2f840 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2f850 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45  nst void *SQLITE
2f860 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2f870 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73  _column_name16(s
2f880 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2f890 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t N);../*.** CAP
2f8a0 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66  I3REF: Source Of
2f8b0 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79   Data In A Query
2f8c0 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f   Result.** METHO
2f8d0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2f8e0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
2f8f0 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20  tines provide a 
2f900 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69  means to determi
2f910 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c  ne the database,
2f920 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74   table, and.** t
2f930 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
2f940 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f   is the origin o
2f950 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  f a particular r
2f960 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a  esult column in.
2f970 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  ** [SELECT] stat
2f980 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e  ement..** ^The n
2f990 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
2f9a0 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20  ase or table or 
2f9b0 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65  column can be re
2f9c0 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74  turned as.** eit
2f9d0 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55  her a UTF-8 or U
2f9e0 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e  TF-16 string.  ^
2f9f0 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72  The _database_ r
2fa00 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a  outines return.*
2fa10 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  * the database n
2fa20 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f  ame, the _table_
2fa30 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2fa40 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c   the table name,
2fa50 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67   and.** the orig
2fa60 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  in_ routines ret
2fa70 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e  urn the column n
2fa80 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ame..** ^The ret
2fa90 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
2faa0 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20  valid until the 
2fab0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2fac0 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65  ent] is destroye
2fad0 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  d.** using [sqli
2fae0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2faf0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61  or until the sta
2fb00 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61  tement is automa
2fb10 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65  tically.** repre
2fb20 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72  pared by the fir
2fb30 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  st call to [sqli
2fb40 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20  te3_step()] for 
2fb50 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e  a particular run
2fb60 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  .** or until the
2fb70 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
2fb80 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a  n is requested.*
2fb90 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66  * again in a dif
2fba0 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e  ferent encoding.
2fbb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
2fbc0 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74  s returned are t
2fbd0 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61  he original un-a
2fbe0 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20  liased names of 
2fbf0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c  the.** database,
2fc00 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75   table, and colu
2fc10 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  mn..**.** ^The f
2fc20 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
2fc30 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
2fc40 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  s is a [prepared
2fc50 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
2fc60 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
2fc70 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
2fc80 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74  ion about the Nt
2fc90 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  h result column 
2fca0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74  returned by.** t
2fcb0 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68  he statement, wh
2fcc0 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
2fcd0 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  ond function arg
2fce0 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c  ument..** ^The l
2fcf0 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  eft-most column 
2fd00 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20  is column 0 for 
2fd10 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
2fd20 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74  **.** ^If the Nt
2fd30 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  h column returne
2fd40 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65  d by the stateme
2fd50 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73  nt is an express
2fd60 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65  ion or.** subque
2fd70 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  ry and is not a 
2fd80 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68  column value, th
2fd90 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  en all of these 
2fda0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
2fdb0 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73  .** NULL.  ^Thes
2fdc0 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20  e routine might 
2fdd0 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c  also return NULL
2fde0 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   if a memory all
2fdf0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a  ocation error.**
2fe00 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72   occurs.  ^Other
2fe10 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72  wise, they retur
2fe20 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
2fe30 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  e attached datab
2fe40 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f  ase, table,.** o
2fe50 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75  r column that qu
2fe60 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  ery result colum
2fe70 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20  n was extracted 
2fe80 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20  from..**.** ^As 
2fe90 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53  with all other S
2fea0 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73  QLite APIs, thos
2feb0 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e  e whose names en
2fec0 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75  d with "16" retu
2fed0 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63  rn.** UTF-16 enc
2fee0 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64  oded strings and
2fef0 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74   the other funct
2ff00 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d  ions return UTF-
2ff10 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  8..**.** ^These 
2ff20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76  APIs are only av
2ff30 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c  ailable if the l
2ff40 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69  ibrary was compi
2ff50 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
2ff60 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43  [SQLITE_ENABLE_C
2ff70 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20  OLUMN_METADATA] 
2ff80 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73  C-preprocessor s
2ff90 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ymbol..**.** If 
2ffa0 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
2ffb0 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
2ffc0 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f  more of these ro
2ffd0 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74  utines against t
2ffe0 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61  he same.** prepa
2fff0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  red statement an
30000 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20  d column at the 
30010 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
30020 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a  he results are.*
30030 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
30040 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
30050 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
30060 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73  ne or more.** [s
30070 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
30080 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f  tabase_name | co
30090 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e  lumn metadata in
300a0 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72  terfaces].** for
300b0 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61   the same [prepa
300c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
300d0 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  nd result column
300e0 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20  .** at the same 
300f0 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
30100 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
30110 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ned..*/.SQLITE_A
30120 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53  PI const char *S
30130 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
30140 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
30150 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74  abase_name(sqlit
30160 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53  e3_stmt*,int);.S
30170 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
30180 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44  void *SQLITE_STD
30190 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  CALL sqlite3_col
301a0 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
301b0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
301c0 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
301d0 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53  PI const char *S
301e0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
301f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
30200 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  le_name(sqlite3_
30210 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49  stmt*,int);.SQLI
30220 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
30230 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  d *SQLITE_STDCAL
30240 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  L sqlite3_column
30250 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71  _table_name16(sq
30260 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
30270 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
30280 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f  st char *SQLITE_
30290 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
302a0 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
302b0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
302c0 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ,int);.SQLITE_AP
302d0 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51  I const void *SQ
302e0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
302f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
30300 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  in_name16(sqlite
30310 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f  3_stmt*,int);../
30320 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
30330 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65  eclared Datatype
30340 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75   Of A Query Resu
30350 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  lt.** METHOD: sq
30360 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
30370 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72   ^(The first par
30380 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65  ameter is a [pre
30390 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
303a0 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61  ..** If this sta
303b0 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c  tement is a [SEL
303c0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61  ECT] statement a
303d0 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  nd the Nth colum
303e0 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75  n of the.** retu
303f0 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20  rned result set 
30400 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d  of that [SELECT]
30410 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75   is a table colu
30420 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78  mn (not an.** ex
30430 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
30440 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64  uery) then the d
30450 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20  eclared type of 
30460 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c  the table.** col
30470 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  umn is returned.
30480 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20  )^  ^If the Nth 
30490 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65  column of the re
304a0 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a  sult set is an.*
304b0 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
304c0 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61  subquery, then a
304d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
304e0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54   returned..** ^T
304f0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
30500 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46  ng is always UTF
30510 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a  -8 encoded..**.*
30520 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  * ^(For example,
30530 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62   given the datab
30540 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a  ase schema:.**.*
30550 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74  * CREATE TABLE t
30560 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a  1(c1 VARIANT);.*
30570 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c  *.** and the fol
30580 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  lowing statement
30590 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a   to be compiled:
305a0 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31  .**.** SELECT c1
305b0 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31   + 1, c1 FROM t1
305c0 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ;.**.** this rou
305d0 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72  tine would retur
305e0 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41  n the string "VA
305f0 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73  RIANT" for the s
30600 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20  econd result.** 
30610 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61  column (i==1), a
30620 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nd a NULL pointe
30630 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  r for the first 
30640 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69  result column (i
30650 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53  ==0).)^.**.** ^S
30660 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d  QLite uses dynam
30670 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69  ic run-time typi
30680 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65  ng.  ^So just be
30690 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a  cause a column.*
306a0 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f  * is declared to
306b0 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69   contain a parti
306c0 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20  cular type does 
306d0 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68  not mean that th
306e0 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64  e.** data stored
306f0 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20   in that column 
30700 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72  is of the declar
30710 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65  ed type.  SQLite
30720 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20   is.** strongly 
30730 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74  typed, but the t
30740 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63  yping is dynamic
30750 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54   not static.  ^T
30760 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69  ype.** is associ
30770 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69  ated with indivi
30780 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74  dual values, not
30790 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69   with the contai
307a0 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20  ners.** used to 
307b0 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65  hold those value
307c0 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  s..*/.SQLITE_API
307d0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c   const char *SQL
307e0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
307f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
30800 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
30810 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
30820 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53  PI const void *S
30830 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
30840 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
30850 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f  ltype16(sqlite3_
30860 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
30870 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61  ** CAPI3REF: Eva
30880 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61  luate An SQL Sta
30890 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44  tement.** METHOD
308a0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
308b0 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72  *.** After a [pr
308c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
308d0 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61  ] has been prepa
308e0 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  red using either
308f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
30900 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
30910 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
30920 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v2()] or one of
30930 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
30940 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74  nterfaces [sqlit
30950 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
30960 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
30970 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e  e16()], this fun
30980 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65  ction.** must be
30990 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d   called one or m
309a0 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61  ore times to eva
309b0 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d  luate the statem
309c0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64  ent..**.** The d
309d0 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65  etails of the be
309e0 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71  havior of the sq
309f0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74  lite3_step() int
30a00 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a  erface depend.**
30a10 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20   on whether the 
30a20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72  statement was pr
30a30 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65  epared using the
30a40 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65   newer "v2" inte
30a50 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  rface.** [sqlite
30a60 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
30a70 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
30a80 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
30a90 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79  the older legacy
30aa0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73  .** interface [s
30ab0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
30ac0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
30ad0 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68  repare16()].  Th
30ae0 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20  e use of the.** 
30af0 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61  new "v2" interfa
30b00 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
30b10 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63  d for new applic
30b20 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c  ations but the l
30b30 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
30b40 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65  ce will continue
30b50 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
30b60 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  ..**.** ^In the 
30b70 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
30b80 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
30b90 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65  ue will be eithe
30ba0 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  r [SQLITE_BUSY],
30bb0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  .** [SQLITE_DONE
30bc0 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ], [SQLITE_ROW],
30bd0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
30be0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   or [SQLITE_MISU
30bf0 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68  SE]..** ^With th
30c00 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
30c10 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68  , any of the oth
30c20 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73  er [result codes
30c30 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
30c40 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
30c50 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65  might be returne
30c60 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a  d as well..**.**
30c70 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20   ^[SQLITE_BUSY] 
30c80 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64  means that the d
30c90 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77  atabase engine w
30ca0 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71  as unable to acq
30cb0 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61  uire the.** data
30cc0 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65  base locks it ne
30cd0 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f  eds to do its jo
30ce0 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74  b.  ^If the stat
30cf0 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d  ement is a [COMM
30d00 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73  IT].** or occurs
30d10 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65   outside of an e
30d20 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
30d30 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61  ion, then you ca
30d40 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73  n retry the.** s
30d50 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68  tatement.  If th
30d60 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
30d70 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e  ot a [COMMIT] an
30d80 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  d occurs within 
30d90 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74  an.** explicit t
30da0 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20  ransaction then 
30db0 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62  you should rollb
30dc0 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
30dd0 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f  ion before.** co
30de0 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  ntinuing..**.** 
30df0 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d  ^[SQLITE_DONE] m
30e00 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74  eans that the st
30e10 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69  atement has fini
30e20 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a  shed executing.*
30e30 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20  * successfully. 
30e40 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
30e50 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
30e60 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68  lled again on th
30e70 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  is virtual.** ma
30e80 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69  chine without fi
30e90 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  rst calling [sql
30ea0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f  ite3_reset()] to
30eb0 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75   reset the virtu
30ec0 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61  al.** machine ba
30ed0 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
30ee0 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e  l state..**.** ^
30ef0 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
30f00 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75  ment being execu
30f10 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20  ted returns any 
30f20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49  data, then [SQLI
30f30 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65  TE_ROW].** is re
30f40 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65  turned each time
30f50 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61   a new row of da
30f60 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20  ta is ready for 
30f70 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68  processing by th
30f80 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65  e.** caller. The
30f90 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61   values may be a
30fa0 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68  ccessed using th
30fb0 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  e [column access
30fc0 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
30fd0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
30fe0 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74  s called again t
30ff0 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e  o retrieve the n
31000 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e  ext row of data.
31010 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
31020 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61  ERROR] means tha
31030 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72  t a run-time err
31040 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f  or (such as a co
31050 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c  nstraint.** viol
31060 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72  ation) has occur
31070 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  red.  sqlite3_st
31080 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
31090 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
310a0 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f  on.** the VM. Mo
310b0 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d  re information m
310c0 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63  ay be found by c
310d0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
310e0 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57  errmsg()]..** ^W
310f0 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69  ith the legacy i
31100 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65  nterface, a more
31110 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
31120 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c  code (for exampl
31130 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  e,.** [SQLITE_IN
31140 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54  TERRUPT], [SQLIT
31150 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49  E_SCHEMA], [SQLI
31160 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64  TE_CORRUPT], and
31170 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61   so forth).** ca
31180 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79  n be obtained by
31190 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
311a0 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68  3_reset()] on th
311b0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
311c0 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20  tatement].  ^In 
311d0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
311e0 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20  ce,.** the more 
311f0 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
31200 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  ode is returned 
31210 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69  directly by sqli
31220 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a  te3_step()..**.*
31230 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  * [SQLITE_MISUSE
31240 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
31250 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61   this routine wa
31260 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f  s called inappro
31270 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72  priately..** Per
31280 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c  haps it was call
31290 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  ed on a [prepare
312a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
312b0 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79  t has.** already
312c0 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   been [sqlite3_f
312d0 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
312e0 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74  zed] or on one t
312f0 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69  hat had.** previ
31300 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b  ously returned [
31310 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72  SQLITE_ERROR] or
31320 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
31330 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20   Or it could.** 
31340 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
31350 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
31360 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
31370 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74   being used by t
31380 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68  wo or.** more th
31390 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
313a0 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65  e moment in time
313b0 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20  ..**.** For all 
313c0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
313d0 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63  te up to and inc
313e0 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c  luding 3.6.23.1,
313f0 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73   a call to.** [s
31400 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
31410 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74  was required aft
31420 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  er sqlite3_step(
31430 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68  ) returned anyth
31440 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61  ing.** other tha
31450 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62  n [SQLITE_ROW] b
31460 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71  efore any subseq
31470 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20  uent invocation 
31480 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  of.** sqlite3_st
31490 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74  ep().  Failure t
314a0 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70  o reset the prep
314b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75  ared statement u
314c0 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  sing .** [sqlite
314d0 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64  3_reset()] would
314e0 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53   result in an [S
314f0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65  QLITE_MISUSE] re
31500 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c  turn from.** sql
31510 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75  ite3_step().  Bu
31520 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20  t after version 
31530 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65  3.6.23.1, sqlite
31540 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a  3_step() began.*
31550 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  * calling [sqlit
31560 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f  e3_reset()] auto
31570 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69  matically in thi
31580 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72  s circumstance r
31590 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65  ather.** than re
315a0 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
315b0 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69  MISUSE].  This i
315c0 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64  s not considered
315d0 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79   a compatibility
315e0 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73  .** break becaus
315f0 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f  e any applicatio
31600 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65  n that ever rece
31610 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d  ives an SQLITE_M
31620 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69  ISUSE error.** i
31630 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69  s broken by defi
31640 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51  nition.  The [SQ
31650 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45  LITE_OMIT_AUTORE
31660 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  SET] compile-tim
31670 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20  e option.** can 
31680 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f  be used to resto
31690 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65  re the legacy be
316a0 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62  havior..**.** <b
316b0 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65  >Goofy Interface
316c0 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74   Alert:</b> In t
316d0 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
316e0 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ace, the sqlite3
316f0 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61  _step().** API a
31700 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20  lways returns a 
31710 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f  generic error co
31720 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  de, [SQLITE_ERRO
31730 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  R], following an
31740 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72  y.** error other
31750 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55   than [SQLITE_BU
31760 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  SY] and [SQLITE_
31770 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75  MISUSE].  You mu
31780 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69  st call.** [sqli
31790 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
317a0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
317b0 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  e()] in order to
317c0 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65   find one of the
317d0 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72  .** specific [er
317e0 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20  ror codes] that 
317f0 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73  better describes
31800 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57   the error..** W
31810 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69  e admit that thi
31820 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73  s is a goofy des
31830 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65  ign.  The proble
31840 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64  m has been fixed
31850 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32  .** with the "v2
31860 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66  " interface.  If
31870 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c   you prepare all
31880 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61   of your SQL sta
31890 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67  tements.** using
318a0 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
318b0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
318c0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
318d0 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65  re16_v2()] inste
318e0 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67  ad.** of the leg
318f0 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  acy [sqlite3_pre
31900 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
31910 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
31920 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a  ] interfaces,.**
31930 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73   then the more s
31940 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63  pecific [error c
31950 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e  odes] are return
31960 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62  ed directly.** b
31970 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
31980 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
31990 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
319a0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e   is recommended.
319b0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
319c0 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
319d0 4c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73  L sqlite3_step(s
319e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
319f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31a00 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  Number of column
31a10 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65  s in a result se
31a20 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
31a30 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
31a40 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
31a50 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72  a_count(P) inter
31a60 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
31a70 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
31a80 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72  ns in the.** cur
31a90 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
31aa0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70  result set of [p
31ab0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
31ac0 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65  t] P..** ^If pre
31ad0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
31ae0 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  P does not have 
31af0 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f  results ready to
31b00 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20   return.** (via 
31b10 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71  calls to the [sq
31b20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
31b30 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d   | sqlite3_colum
31b40 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74  n_*()] of.** int
31b50 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71  erfaces) then sq
31b60 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
31b70 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a  (P) returns 0..*
31b80 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
31b90 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75  ata_count(P) rou
31ba0 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e  tine also return
31bb0 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55  s 0 if P is a NU
31bc0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e  LL pointer..** ^
31bd0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
31be0 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e  _count(P) routin
31bf0 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74  e returns 0 if t
31c00 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
31c10 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
31c20 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65  step](P) returne
31c30 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  d [SQLITE_DONE].
31c40 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64    ^The sqlite3_d
31c50 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20  ata_count(P).** 
31c60 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d  will return non-
31c70 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73  zero if previous
31c80 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
31c90 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72  3_step](P) retur
31ca0 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52  ned.** [SQLITE_R
31cb0 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74  OW], except in t
31cc0 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b  he case of the [
31cd0 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74  PRAGMA increment
31ce0 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68  al_vacuum].** wh
31cf0 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65  ere it always re
31d00 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65  turns zero since
31d10 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68   each step of th
31d20 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a  at multi-step.**
31d30 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20   pragma returns 
31d40 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74  0 columns of dat
31d50 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  a..**.** See als
31d60 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  o: [sqlite3_colu
31d70 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53  mn_count()].*/.S
31d80 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
31d90 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
31da0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
31db0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
31dc0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
31dd0 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74  I3REF: Fundament
31de0 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20  al Datatypes.** 
31df0 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
31e00 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76  _TEXT.**.** ^(Ev
31e10 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c  ery value in SQL
31e20 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66  ite has one of f
31e30 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20  ive fundamental 
31e40 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a  datatypes:.**.**
31e50 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34   <ul>.** <li> 64
31e60 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
31e70 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ger.** <li> 64-b
31e80 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67  it IEEE floating
31e90 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a   point number.**
31ea0 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20   <li> string.** 
31eb0 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69  <li> BLOB.** <li
31ec0 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29  > NULL.** </ul>)
31ed0 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  ^.**.** These co
31ee0 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65  nstants are code
31ef0 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68  s for each of th
31f00 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a  ose types..**.**
31f10 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53   Note that the S
31f20 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74  QLITE_TEXT const
31f30 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65  ant was also use
31f40 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73  d in SQLite vers
31f50 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63  ion 2.** for a c
31f60 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72  ompletely differ
31f70 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f  ent meaning.  So
31f80 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b  ftware that link
31f90 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a  s against both.*
31fa0 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
31fb0 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65   2 and SQLite ve
31fc0 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75  rsion 3 should u
31fd0 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c  se SQLITE3_TEXT,
31fe0 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54   not.** SQLITE_T
31ff0 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  EXT..*/.#define 
32000 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20  SQLITE_INTEGER  
32010 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
32020 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66  _FLOAT    2.#def
32030 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20  ine SQLITE_BLOB 
32040 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
32050 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a  LITE_NULL     5.
32060 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45  #ifdef SQLITE_TE
32070 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54  XT.# undef SQLIT
32080 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64  E_TEXT.#else.# d
32090 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58  efine SQLITE_TEX
320a0 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23  T     3.#endif.#
320b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54  define SQLITE3_T
320c0 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a  EXT     3../*.**
320d0 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
320e0 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20  t Values From A 
320f0 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44  Query.** KEYWORD
32100 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  S: {column acces
32110 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20  s functions}.** 
32120 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
32130 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  stmt.**.** ^Thes
32140 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
32150 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  n information ab
32160 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c  out a single col
32170 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  umn of the curre
32180 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77  nt.** result row
32190 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49   of a query.  ^I
321a0 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65  n every case the
321b0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
321c0 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  is a pointer.** 
321d0 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  to the [prepared
321e0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
321f0 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61   is being evalua
32200 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ted (the [sqlite
32210 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74  3_stmt*].** that
32220 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72   was returned fr
32230 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  om [sqlite3_prep
32240 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  are_v2()] or one
32250 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73   of its variants
32260 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63  ).** and the sec
32270 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
32280 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
32290 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63   column for whic
322a0 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  h information.**
322b0 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
322c0 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f  ned. ^The leftmo
322d0 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  st column of the
322e0 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20   result set has 
322f0 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20  the index 0..** 
32300 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63  ^The number of c
32310 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
32320 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65  sult can be dete
32330 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20  rmined using.** 
32340 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
32350 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  count()]..**.** 
32360 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
32370 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75  ment does not cu
32380 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f  rrently point to
32390 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72   a valid row, or
323a0 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   if the.** colum
323b0 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  n index is out o
323c0 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73  f range, the res
323d0 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ult is undefined
323e0 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
323f0 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  nes may only be 
32400 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20  called when the 
32410 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
32420 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
32430 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
32440 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
32450 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a  ] and neither.**
32460 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
32470 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )] nor [sqlite3_
32480 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65  finalize()] have
32490 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62   been called sub
324a0 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66  sequently..** If
324b0 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
324c0 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
324d0 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  d after [sqlite3
324e0 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
324f0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
32500 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73  e()] or after [s
32510 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
32520 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73  as returned.** s
32530 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
32540 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
32550 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  , the results ar
32560 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  e undefined..** 
32570 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  If [sqlite3_step
32580 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
32590 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
325a0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
325b0 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66  .** are called f
325c0 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20  rom a different 
325d0 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79  thread while any
325e0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
325f0 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e  es.** are pendin
32600 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  g, then the resu
32610 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
32620 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
32630 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
32640 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  e() routine retu
32650 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  rns the.** [SQLI
32660 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
32670 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20  atype code] for 
32680 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61  the initial data
32690 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20   type.** of the 
326a0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20  result column.  
326b0 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61  ^The returned va
326c0 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  lue is one of [S
326d0 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a  QLITE_INTEGER],.
326e0 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ** [SQLITE_FLOAT
326f0 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d  ], [SQLITE_TEXT]
32700 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c  , [SQLITE_BLOB],
32710 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c   or [SQLITE_NULL
32720 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a  ].  The value.**
32730 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
32740 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
32750 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69  () is only meani
32760 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65  ngful if no type
32770 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  .** conversions 
32780 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73  have occurred as
32790 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77   described below
327a0 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20  .  After a type 
327b0 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74  conversion,.** t
327c0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
327d0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
327e0 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e  umn_type() is un
327f0 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65  defined.  Future
32800 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  .** versions of 
32810 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67  SQLite may chang
32820 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  e the behavior o
32830 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  f sqlite3_column
32840 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f  _type().** follo
32850 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76  wing a type conv
32860 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ersion..**.** ^I
32870 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
32880 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20  a BLOB or UTF-8 
32890 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20  string then the 
328a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
328b0 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  ytes().** routin
328c0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
328d0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
328e0 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
328f0 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
32900 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
32910 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  -16 string, then
32920 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
32930 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73  bytes() converts
32940 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
32950 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e  o UTF-8 and then
32960 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
32970 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a  ber of bytes..**
32980 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
32990 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c  is a numeric val
329a0 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ue then sqlite3_
329b0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75  column_bytes() u
329c0 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ses.** [sqlite3_
329d0 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63  snprintf()] to c
329e0 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75  onvert that valu
329f0 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72  e to a UTF-8 str
32a00 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
32a10 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
32a20 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
32a30 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
32a40 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  e result is NULL
32a50 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
32a60 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65  olumn_bytes() re
32a70 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
32a80 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
32a90 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
32aa0 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e  F-16 string then
32ab0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
32ac0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a  umn_bytes16().**
32ad0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
32ae0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
32af0 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f  ytes in that BLO
32b00 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  B or string..** 
32b10 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
32b20 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  s a UTF-8 string
32b30 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
32b40 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
32b50 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
32b60 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36  string to UTF-16
32b70 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
32b80 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
32b90 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  bytes..** ^If th
32ba0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
32bb0 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
32bc0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
32bd0 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a  bytes16() uses.*
32be0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  * [sqlite3_snpri
32bf0 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72  ntf()] to conver
32c00 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20  t that value to 
32c10 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  a UTF-16 string 
32c20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
32c30 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
32c40 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
32c50 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
32c60 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
32c70 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
32c80 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 75  n_bytes16() retu
32c90 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
32ca0 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75  ^The values retu
32cb0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
32cc0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d  _column_bytes()]
32cd0 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   and .** [sqlite
32ce0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
32cf0 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75  ()] do not inclu
32d00 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  de the zero term
32d10 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 65  inators at the e
32d20 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72  nd.** of the str
32d30 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69  ing.  ^For clari
32d40 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72  ty: the values r
32d50 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
32d60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
32d70 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tes()] and [sqli
32d80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
32d90 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75  16()] are the nu
32da0 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73  mber of.** bytes
32db0 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20   in the string, 
32dc0 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
32dd0 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  f characters..**
32de0 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74  .** ^Strings ret
32df0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
32e00 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61  _column_text() a
32e10 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
32e20 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65  n_text16(),.** e
32e30 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67  ven empty string
32e40 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65  s, are always ze
32e50 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro-terminated.  
32e60 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76  ^The return.** v
32e70 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
32e80 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
32e90 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74  for a zero-lengt
32ea0 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c  h BLOB is a NULL
32eb0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
32ec0 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20  <b>Warning:</b> 
32ed0 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75  ^The object retu
32ee0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
32ef0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
32f00 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f   is an.** [unpro
32f10 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
32f20 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49  alue] object.  I
32f30 6e 20 61 20 6d 75 6c 74 69 74 68 72 65 61 64 65  n a multithreade
32f40 64 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a  d environment,.*
32f50 2a 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  * an unprotected
32f60 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
32f70 62 6a 65 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62  bject may only b
32f80 65 20 75 73 65 64 20 73 61 66 65 6c 79 20 77 69  e used safely wi
32f90 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  th.** [sqlite3_b
32fa0 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64  ind_value()] and
32fb0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
32fc0 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66  _value()]..** If
32fd0 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65   the [unprotecte
32fe0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
32ff0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
33000 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
33010 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
33020 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f  is used in any o
33030 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64  ther way, includ
33040 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  ing calls.** to 
33050 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
33060 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
33070 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
33080 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20  lue_text()],.** 
33090 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  or [sqlite3_valu
330a0 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 20  e_bytes()], the 
330b0 62 65 68 61 76 69 6f 72 20 69 73 20 6e 6f 74 20  behavior is not 
330c0 74 68 72 65 61 64 73 61 66 65 2e 0a 2a 2a 0a 2a  threadsafe..**.*
330d0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
330e0 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76   attempt to conv
330f0 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68  ert the value wh
33100 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e  ere appropriate.
33110 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c    ^For.** exampl
33120 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e  e, if the intern
33130 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
33140 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61  n is FLOAT and a
33150 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20   text result.** 
33160 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73  is requested, [s
33170 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
33180 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72  )] is used inter
33190 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d  nally to perform
331a0 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69   the.** conversi
331b0 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  on automatically
331c0 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69  .  ^(The followi
331d0 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73  ng table details
331e0 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73   the conversions
331f0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70  .** that are app
33200 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lied:.**.** <blo
33210 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62  ckquote>.** <tab
33220 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a  le border="1">.*
33230 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72  * <tr><th> Inter
33240 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  nal<br>Type <th>
33250 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79   Requested<br>Ty
33260 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73  pe <th>  Convers
33270 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74  ion.**.** <tr><t
33280 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
33290 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
332a0 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c  Result is 0.** <
332b0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
332c0 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
332d0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
332e0 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  .0.** <tr><td>  
332f0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54  NULL    <td>   T
33300 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  EXT    <td> Resu
33310 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  lt is a NULL poi
33320 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
33330 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
33340 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65   BLOB    <td> Re
33350 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  sult is a NULL p
33360 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
33370 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
33380 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
33390 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74  Convert from int
333a0 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a  eger to float.**
333b0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
333c0 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20  R  <td>   TEXT  
333d0 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
333e0 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e  dering of the in
333f0 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
33400 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
33410 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
33420 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e  ame as INTEGER->
33430 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
33440 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49    FLOAT   <td> I
33450 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43  NTEGER   <td> [C
33460 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a  AST] to INTEGER.
33470 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
33480 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  AT   <td>   TEXT
33490 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
334a0 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
334b0 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
334c0 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
334d0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b    BLOB    <td> [
334e0 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a  CAST] to BLOB.**
334f0 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
33500 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
33510 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
33520 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e   INTEGER.** <tr>
33530 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
33540 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
33550 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c  > [CAST] to REAL
33560 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
33570 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  XT    <td>   BLO
33580 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61  B    <td> No cha
33590 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  nge.** <tr><td> 
335a0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e   BLOB    <td> IN
335b0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41  TEGER   <td> [CA
335c0 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a  ST] to INTEGER.*
335d0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
335e0 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
335f0 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
33600 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74  o REAL.** <tr><t
33610 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
33620 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
33630 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69  Add a zero termi
33640 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a  nator if needed.
33650 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c  ** </table>.** <
33660 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
33670 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77  *.** Note that w
33680 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73  hen type convers
33690 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e  ions occur, poin
336a0 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79  ters returned by
336b0 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20   prior.** calls 
336c0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
336d0 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  n_blob(), sqlite
336e0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
336f0 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74   and/or.** sqlit
33700 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
33710 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69  () may be invali
33720 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63  dated..** Type c
33730 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70  onversions and p
33740 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74  ointer invalidat
33750 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72  ions might occur
33760 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f  .** in the follo
33770 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a  wing cases:.**.*
33780 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
33790 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
337a0 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64  nt is a BLOB and
337b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
337c0 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20  text() or.**    
337d0 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
337e0 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
337f0 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72  led.  A zero-ter
33800 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a  minator might.**
33810 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65        need to be
33820 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74   added to the st
33830 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  ring.</li>.** <l
33840 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
33850 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20  ontent is UTF-8 
33860 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
33870 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
33880 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
33890 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
338a0 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
338b0 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
338c0 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
338d0 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36  *      to UTF-16
338e0 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
338f0 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
33900 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78  nt is UTF-16 tex
33910 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
33920 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
33930 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
33940 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73  column_text() is
33950 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
33960 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
33970 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
33980 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a  to UTF-8.</li>.*
33990 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43  * </ul>.**.** ^C
339a0 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65  onversions betwe
339b0 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20  en UTF-16be and 
339c0 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77  UTF-16le are alw
339d0 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  ays done in plac
339e0 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20  e and do.** not 
339f0 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69  invalidate a pri
33a00 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75  or pointer, thou
33a10 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65  gh of course the
33a20 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
33a30 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74  buffer.** that t
33a40 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  he prior pointer
33a50 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c   references will
33a60 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66   have been modif
33a70 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64  ied.  Other kind
33a80 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69  s.** of conversi
33a90 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70  on are done in p
33aa0 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20  lace when it is 
33ab0 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f  possible, but so
33ac0 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20  metimes they.** 
33ad0 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65  are not possible
33ae0 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61   and in those ca
33af0 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  ses prior pointe
33b00 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74  rs are invalidat
33b10 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61  ed..**.** The sa
33b20 66 65 73 74 20 70 6f 6c 69 63 79 20 69 73 20 74  fest policy is t
33b30 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72  o invoke these r
33b40 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e  outines.** in on
33b50 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
33b60 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ng ways:.**.** <
33b70 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  ul>.**  <li>sqli
33b80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
33b90 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
33ba0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
33bb0 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
33bc0 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
33bd0 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64  _blob() followed
33be0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
33bf0 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
33c00 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
33c10 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
33c20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
33c30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
33c40 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  16()</li>.** </u
33c50 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65  l>.**.** In othe
33c60 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f  r words, you sho
33c70 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  uld call sqlite3
33c80 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a  _column_text(),.
33c90 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
33ca0 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c  n_blob(), or sql
33cb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
33cc0 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f  16() first to fo
33cd0 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a  rce the result.*
33ce0 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72  * into the desir
33cf0 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20  ed format, then 
33d00 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
33d10 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
33d20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
33d30 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20  mn_bytes16() to 
33d40 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66  find the size of
33d50 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f   the result.  Do
33d60 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a   not mix calls.*
33d70 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  * to sqlite3_col
33d80 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71  umn_text() or sq
33d90 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
33da0 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74  b() with calls t
33db0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
33dc0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61  umn_bytes16(), a
33dd0 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61  nd do not mix ca
33de0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
33df0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a  olumn_text16().*
33e00 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20  * with calls to 
33e10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
33e20 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ytes()..**.** ^T
33e30 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
33e40 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75  rned are valid u
33e50 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76  ntil a type conv
33e60 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73  ersion occurs as
33e70 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62  .** described ab
33e80 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73  ove, or until [s
33e90 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
33ea0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
33eb0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
33ec0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
33ed0 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20  s called.  ^The 
33ee0 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65  memory space use
33ef0 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67  d to hold string
33f00 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69  s.** and BLOBs i
33f10 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69  s freed automati
33f20 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 65 6d 3e 6e  cally.  Do <em>n
33f30 6f 74 3c 2f 65 6d 3e 20 70 61 73 73 20 74 68 65  ot</em> pass the
33f40 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
33f50 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
33f60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
33f70 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  )], [sqlite3_col
33f80 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63  umn_text()], etc
33f90 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  . into.** [sqlit
33fa0 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a  e3_free()]..**.*
33fb0 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20  * ^(If a memory 
33fc0 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
33fd0 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74   occurs during t
33fe0 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  he evaluation of
33ff0 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65   any.** of these
34000 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66   routines, a def
34010 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65  ault value is re
34020 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66  turned.  The def
34030 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73  ault value.** is
34040 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65   either the inte
34050 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74  ger 0, the float
34060 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
34070 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a   0.0, or a NULL.
34080 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62  ** pointer.  Sub
34090 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
340a0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
340b0 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  e()] will return
340c0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .** [SQLITE_NOME
340d0 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  M].)^.*/.SQLITE_
340e0 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
340f0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
34100 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
34110 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
34120 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
34130 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
34140 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
34150 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
34160 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
34170 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
34180 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
34190 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
341a0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73  column_bytes16(s
341b0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
341c0 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
341d0 41 50 49 20 64 6f 75 62 6c 65 20 53 51 4c 49 54  API double SQLIT
341e0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
341f0 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28  3_column_double(
34200 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
34210 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
34220 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
34230 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
34240 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74  column_int(sqlit
34250 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
34260 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
34270 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 53 51  sqlite3_int64 SQ
34280 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
34290 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36  ite3_column_int6
342a0 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
342b0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
342c0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73  TE_API const uns
342d0 69 67 6e 65 64 20 63 68 61 72 20 2a 53 51 4c 49  igned char *SQLI
342e0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
342f0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73  e3_column_text(s
34300 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
34310 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
34320 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
34330 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
34340 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
34350 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
34360 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
34370 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
34380 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
34390 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
343a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
343b0 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
343c0 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 76 61  E_API sqlite3_va
343d0 6c 75 65 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  lue *SQLITE_STDC
343e0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ALL sqlite3_colu
343f0 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  mn_value(sqlite3
34400 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
34410 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
34420 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72  EF: Destroy A Pr
34430 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
34440 20 4f 62 6a 65 63 74 0a 2a 2a 20 44 45 53 54 52   Object.** DESTR
34450 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73  UCTOR: sqlite3_s
34460 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  tmt.**.** ^The s
34470 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
34480 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
34490 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61  lled to delete a
344a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
344b0 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  ment]..** ^If th
344c0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76  e most recent ev
344d0 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  aluation of the 
344e0 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e  statement encoun
344f0 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a  tered no errors.
34500 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61  ** or if the sta
34510 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20  tement is never 
34520 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20  been evaluated, 
34530 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e  then sqlite3_fin
34540 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a  alize() returns.
34550 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e  ** SQLITE_OK.  ^
34560 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
34570 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  nt evaluation of
34580 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69   statement S fai
34590 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  led, then.** sql
345a0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
345b0 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70   returns the app
345c0 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
345d0 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  code] or.** [ext
345e0 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
345f0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
34600 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
34610 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  ) routine can be
34620 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70   called at any p
34630 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74  oint during.** t
34640 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66  he life cycle of
34650 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
34660 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f  ment] S:.** befo
34670 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69  re statement S i
34680 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64  s ever evaluated
34690 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f  , after.** one o
346a0 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20  r more calls to 
346b0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
346c0 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20  ], or after any 
346d0 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  call.** to [sqli
346e0 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61  te3_step()] rega
346f0 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
34700 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61  r or not the sta
34710 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f  tement has.** co
34720 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f  mpleted executio
34730 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69  n..**.** ^Invoki
34740 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  ng sqlite3_final
34750 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20  ize() on a NULL 
34760 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72  pointer is a har
34770 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a  mless no-op..**.
34780 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
34790 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65  on must finalize
347a0 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64   every [prepared
347b0 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f   statement] in o
347c0 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  rder to avoid.**
347d0 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e   resource leaks.
347e0 20 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f    It is a grievo
347f0 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65  us error for the
34800 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
34810 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20  try to use.** a 
34820 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
34830 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20  nt after it has 
34840 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20  been finalized. 
34850 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72   Any use of a pr
34860 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
34870 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73  ent after it has
34880 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20   been finalized 
34890 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e  can result in un
348a0 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75  defined and.** u
348b0 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76  ndesirable behav
348c0 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66  ior such as segf
348d0 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63  aults and heap c
348e0 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51  orruption..*/.SQ
348f0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
34900 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
34910 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c  te3_finalize(sql
34920 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
34930 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
34940 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70  EF: Reset A Prep
34950 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
34960 62 6a 65 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  bject.** METHOD:
34970 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
34980 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
34990 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e  reset() function
349a0 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65   is called to re
349b0 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20  set a [prepared 
349c0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
349d0 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73  ject back to its
349e0 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20   initial state, 
349f0 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65  ready to be re-e
34a00 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79  xecuted..** ^Any
34a10 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76   SQL statement v
34a20 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61  ariables that ha
34a30 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74  d values bound t
34a40 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20  o them using.** 
34a50 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
34a60 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  d_blob | sqlite3
34a70 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72  _bind_*() API] r
34a80 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75  etain their valu
34a90 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69  es..** Use [sqli
34aa0 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
34ab0 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  gs()] to reset t
34ac0 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a  he bindings..**.
34ad0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
34ae0 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
34af0 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20  face resets the 
34b00 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
34b10 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74  ent] S.** back t
34b20 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
34b30 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a  of its program..
34b40 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
34b50 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
34b60 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
34b70 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b  S)] for the.** [
34b80 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
34b90 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b  nt] S returned [
34ba0 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b  SQLITE_ROW] or [
34bb0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a  SQLITE_DONE],.**
34bc0 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   or if [sqlite3_
34bd0 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76  step(S)] has nev
34be0 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63  er before been c
34bf0 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74  alled on S,.** t
34c00 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  hen [sqlite3_res
34c10 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b  et(S)] returns [
34c20 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
34c30 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
34c40 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
34c50 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
34c60 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  for the.** [prep
34c70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
34c80 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65  S indicated an e
34c90 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73  rror, then.** [s
34ca0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
34cb0 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72   returns an appr
34cc0 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
34cd0 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode]..**.** ^The
34ce0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
34cf0 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f  S)] interface do
34d00 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
34d10 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61  e values.** of a
34d20 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ny [sqlite3_bind
34d30 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20  _blob|bindings] 
34d40 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  on the [prepared
34d50 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
34d60 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
34d70 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
34d80 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71  sqlite3_reset(sq
34d90 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
34da0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
34db0 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52  REF: Create Or R
34dc0 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63  edefine SQL Func
34dd0 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  tions.** KEYWORD
34de0 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65  S: {function cre
34df0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a  ation routines}.
34e00 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
34e10 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
34e20 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a  d SQL function}.
34e30 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
34e40 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
34e50 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d  d SQL functions}
34e60 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
34e70 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  te3.**.** ^These
34e80 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c   functions (coll
34e90 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61  ectively known a
34ea0 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  s "function crea
34eb0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a  tion routines").
34ec0 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61  ** are used to a
34ed0 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  dd SQL functions
34ee0 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f   or aggregates o
34ef0 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68  r to redefine th
34f00 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66  e behavior.** of
34f10 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75   existing SQL fu
34f20 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
34f30 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79  gates.  The only
34f40 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74   differences bet
34f50 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f  ween.** these ro
34f60 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74  utines are the t
34f70 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70  ext encoding exp
34f80 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65  ected for.** the
34f90 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
34fa0 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  r (the name of t
34fb0 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e  he function bein
34fc0 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e  g created).** an
34fd0 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f  d the presence o
34fe0 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64  r absence of a d
34ff0 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61  estructor callba
35000 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70  ck for.** the ap
35010 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
35020 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
35030 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
35040 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62  er is the [datab
35050 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
35060 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c  to which the SQL
35070 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
35080 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49  to be added.  ^I
35090 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
350a0 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20   uses more than 
350b0 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  one database.** 
350c0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20  connection then 
350d0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
350e0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
350f0 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a  s must be added.
35100 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ** to each datab
35110 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
35120 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  eparately..**.**
35130 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
35140 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
35150 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75  me of the SQL fu
35160 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65  nction to be cre
35170 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66  ated or.** redef
35180 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67  ined.  ^The leng
35190 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69  th of the name i
351a0 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35  s limited to 255
351b0 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d   bytes in a UTF-
351c0 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74  8.** representat
351d0 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f  ion, exclusive o
351e0 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  f the zero-termi
351f0 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68  nator.  ^Note th
35200 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c  at the name.** l
35210 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69  ength limit is i
35220 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e  n UTF-8 bytes, n
35230 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f  ot characters no
35240 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20  r UTF-16 bytes. 
35250 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70   .** ^Any attemp
35260 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75  t to create a fu
35270 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f  nction with a lo
35280 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c  nger name.** wil
35290 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c  l result in [SQL
352a0 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e  ITE_MISUSE] bein
352b0 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  g returned..**.*
352c0 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72  * ^The third par
352d0 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a  ameter (nArg).**
352e0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
352f0 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  f arguments that
35300 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
35310 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
35320 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69  e takes. ^If thi
35330 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d  s parameter is -
35340 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  1, then the SQL 
35350 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
35360 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b  ggregate may tak
35370 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20  e any number of 
35380 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65  arguments betwee
35390 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69  n 0 and the limi
353a0 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c  t.** set by [sql
353b0 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c  ite3_limit]([SQL
353c0 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
353d0 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68  ON_ARG]).  If th
353e0 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
353f0 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61  eter is less tha
35400 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20  n -1 or greater 
35410 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68  than 127 then th
35420 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a  e behavior is.**
35430 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
35440 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
35450 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65  rameter, eTextRe
35460 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61  p, specifies wha
35470 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  t.** [SQLITE_UTF
35480 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  8 | text encodin
35490 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63  g] this SQL func
354a0 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72  tion prefers for
354b0 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65  .** its paramete
354c0 72 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61  rs.  The applica
354d0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74 20  tion should set 
354e0 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 74  this parameter t
354f0 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  o.** [SQLITE_UTF
35500 31 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75 6e  16LE] if the fun
35510 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
35520 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a  tion invokes .**
35530 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
35540 74 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61  text16le()] on a
35550 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c  n input, or [SQL
35560 49 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66 20  ITE_UTF16BE] if 
35570 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
35580 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73  ation invokes [s
35590 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
355a0 74 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69  t16be()] on an i
355b0 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c  nput, or.** [SQL
355c0 49 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b 73  ITE_UTF16] if [s
355d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
355e0 74 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20  t16()] is used, 
355f0 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  or [SQLITE_UTF8]
35600 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20 20  .** otherwise.  
35610 5e 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75  ^The same SQL fu
35620 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65  nction may be re
35630 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c  gistered multipl
35640 65 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a  e times using.**
35650 20 64 69 66 66 65 72 65 6e 74 20 70 72 65 66 65   different prefe
35660 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
35670 6e 67 73 2c 20 77 69 74 68 20 64 69 66 66 65 72  ngs, with differ
35680 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ent implementati
35690 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ons for.** each 
356a0 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68  encoding..** ^Wh
356b0 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  en multiple impl
356c0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
356d0 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
356e0 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20   are available, 
356f0 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70  SQLite.** will p
35700 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74  ick the one that
35710 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65   involves the le
35720 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61  ast amount of da
35730 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  ta conversion..*
35740 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
35750 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 6f   parameter may o
35760 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65  ptionally be ORe
35770 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44  d with [SQLITE_D
35780 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a  ETERMINISTIC].**
35790 20 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74 20   to signal that 
357a0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  the function wil
357b0 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  l always return 
357c0 74 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74 20  the same result 
357d0 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d  given.** the sam
357e0 65 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e 20  e inputs within 
357f0 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
35800 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51  tement.  Most SQ
35810 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a  L functions are.
35820 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63  ** deterministic
35830 2e 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e 20  .  The built-in 
35840 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66  [random()] SQL f
35850 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65 78  unction is an ex
35860 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75  ample of a.** fu
35870 6e 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6e  nction that is n
35880 6f 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63  ot deterministic
35890 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 71 75  .  The SQLite qu
358a0 65 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20 61  ery planner is a
358b0 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72  ble to.** perfor
358c0 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74  m additional opt
358d0 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65  imizations on de
358e0 74 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e 63  terministic func
358f0 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a  tions, so use.**
35900 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
35910 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20 66  DETERMINISTIC] f
35920 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  lag is recommend
35930 65 64 20 77 68 65 72 65 20 70 6f 73 73 69 62 6c  ed where possibl
35940 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  e..**.** ^(The f
35950 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  ifth parameter i
35960 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70  s an arbitrary p
35970 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70  ointer.  The imp
35980 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
35990 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63  he.** function c
359a0 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74  an gain access t
359b0 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75  o this pointer u
359c0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73  sing [sqlite3_us
359d0 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a  er_data()].)^.**
359e0 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20  .** ^The sixth, 
359f0 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68  seventh and eigh
35a00 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78  th parameters, x
35a10 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20  Func, xStep and 
35a20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70  xFinal, are.** p
35a30 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e  ointers to C-lan
35a40 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20  guage functions 
35a50 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
35a60 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
35a70 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e  or.** aggregate.
35a80 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66   ^A scalar SQL f
35a90 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
35aa0 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
35ab0 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a  on of the xFunc.
35ac0 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79  ** callback only
35ad0 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  ; NULL pointers 
35ae0 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61  must be passed a
35af0 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20  s the xStep and 
35b00 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65  xFinal.** parame
35b10 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67  ters. ^An aggreg
35b20 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
35b30 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
35b40 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78  lementation of x
35b50 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e  Step.** and xFin
35b60 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e  al and NULL poin
35b70 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73  ter must be pass
35b80 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54  ed for xFunc. ^T
35b90 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73  o delete an exis
35ba0 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63  ting.** SQL func
35bb0 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
35bc0 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69  e, pass NULL poi
35bd0 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68  nters for all th
35be0 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ree function.** 
35bf0 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a  callbacks..**.**
35c00 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20   ^(If the ninth 
35c10 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
35c20 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
35c30 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  tion_v2() is not
35c40 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69   NULL,.** then i
35c50 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20  t is destructor 
35c60 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  for the applicat
35c70 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
35c80 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75  . .** The destru
35c90 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20  ctor is invoked 
35ca0 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f  when the functio
35cb0 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69  n is deleted, ei
35cc0 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a  ther by being.**
35cd0 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77   overloaded or w
35ce0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
35cf0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
35d00 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65  es.)^.** ^The de
35d10 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f  structor is also
35d20 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20   invoked if the 
35d30 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
35d40 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
35d50 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a  on_v2() fails..*
35d60 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74  * ^When the dest
35d70 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20  ructor callback 
35d80 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72  of the tenth par
35d90 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65  ameter is invoke
35da0 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73  d, it.** is pass
35db0 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  ed a single argu
35dc0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
35dd0 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c  copy of the appl
35de0 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a  ication data .**
35df0 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77   pointer which w
35e00 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72  as the fifth par
35e10 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
35e20 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
35e30 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49  n_v2()..**.** ^I
35e40 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  t is permitted t
35e50 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69  o register multi
35e60 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
35e70 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a  ons of the same.
35e80 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74  ** functions wit
35e90 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  h the same name 
35ea0 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20  but with either 
35eb0 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72  differing number
35ec0 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  s of.** argument
35ed0 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70  s or differing p
35ee0 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
35ef0 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74  codings.  ^SQLit
35f00 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68  e will use.** th
35f10 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
35f20 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65   that most close
35f30 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77  ly matches the w
35f40 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a  ay in which the.
35f50 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
35f60 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e  is used.  ^A fun
35f70 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
35f80 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d  tion with a non-
35f90 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67  negative.** nArg
35fa0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
35fb0 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61  better match tha
35fc0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  n a function imp
35fd0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68  lementation with
35fe0 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e  .** a negative n
35ff0 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f  Arg.  ^A functio
36000 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66  n where the pref
36010 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
36020 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74  ing.** matches t
36030 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f  he database enco
36040 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72  ding is a better
36050 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61  .** match than a
36060 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
36070 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  the encoding is 
36080 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20  different.  .** 
36090 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72  ^A function wher
360a0 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64  e the encoding d
360b0 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74  ifference is bet
360c0 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64  ween UTF16le and
360d0 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61   UTF16be.** is a
360e0 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68   closer match th
360f0 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
36100 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
36110 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a   difference is.*
36120 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61  * between UTF8 a
36130 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20  nd UTF16..**.** 
36140 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69  ^Built-in functi
36150 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c  ons may be overl
36160 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70  oaded by new app
36170 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
36180 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a   functions..**.*
36190 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  * ^An applicatio
361a0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
361b0 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  on is permitted 
361c0 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a  to call other.**
361d0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
361e0 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75  es.  However, su
361f0 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f  ch calls must no
36200 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64  t.** close the d
36210 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
36220 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20  on nor finalize 
36230 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65  or reset the pre
36240 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
36250 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20  nt in which the 
36260 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
36270 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ing..*/.SQLITE_A
36280 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
36290 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 72  DCALL sqlite3_cr
362a0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20  eate_function(. 
362b0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
362c0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e  const char *zFun
362d0 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
362e0 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
362f0 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
36300 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
36310 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
36320 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
36330 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
36340 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
36350 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
36360 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
36370 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
36380 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
36390 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f  ext*).);.SQLITE_
363a0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
363b0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
363c0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
363d0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
363e0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
363f0 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
36400 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
36410 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
36420 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
36430 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
36440 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
36450 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
36460 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
36470 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
36480 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
36490 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
364a0 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
364b0 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49  ontext*).);.SQLI
364c0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
364d0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
364e0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
364f0 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  n_v2(.  sqlite3 
36500 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  *db,.  const cha
36510 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  r *zFunctionName
36520 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
36530 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
36540 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
36550 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
36560 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
36570 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
36580 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
36590 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
365a0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
365b0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
365c0 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
365d0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20  e3_context*),.  
365e0 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28  void(*xDestroy)(
365f0 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  void*).);../*.**
36600 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20   CAPI3REF: Text 
36610 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20  Encodings.**.** 
36620 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64  These constant d
36630 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f  efine integer co
36640 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65  des that represe
36650 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a  nt the various.*
36660 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  * text encodings
36670 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
36680 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  Lite..*/.#define
36690 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20   SQLITE_UTF8    
366a0 20 20 20 20 20 20 20 31 20 20 20 20 2f 2a 20 49         1    /* I
366b0 4d 50 3a 20 52 2d 33 37 35 31 34 2d 33 35 35 36  MP: R-37514-3556
366c0 36 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  6 */.#define SQL
366d0 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20  ITE_UTF16LE     
366e0 20 20 20 32 20 20 20 20 2f 2a 20 49 4d 50 3a 20     2    /* IMP: 
366f0 52 2d 30 33 33 37 31 2d 33 37 36 33 37 20 2a 2f  R-03371-37637 */
36700 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
36710 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33  UTF16BE        3
36720 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 35 31      /* IMP: R-51
36730 39 37 31 2d 33 34 31 35 34 20 2a 2f 0a 23 64 65  971-34154 */.#de
36740 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
36750 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20  6          4    
36760 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79  /* Use native by
36770 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66  te order */.#def
36780 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20  ine SQLITE_ANY  
36790 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f            5    /
367a0 2a 20 44 65 70 72 65 63 61 74 65 64 20 2a 2f 0a  * Deprecated */.
367b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
367c0 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20  TF16_ALIGNED  8 
367d0 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72     /* sqlite3_cr
367e0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f  eate_collation o
367f0 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  nly */../*.** CA
36800 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e  PI3REF: Function
36810 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Flags.**.** The
36820 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79  se constants may
36830 20 62 65 20 4f 52 65 64 20 74 6f 67 65 74 68 65   be ORed togethe
36840 72 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b  r with the .** [
36850 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 70 72  SQLITE_UTF8 | pr
36860 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
36870 6f 64 69 6e 67 5d 20 61 73 20 74 68 65 20 66 6f  oding] as the fo
36880 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  urth argument.**
36890 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
368a0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
368b0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
368c0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 20  _function16()], 
368d0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  or.** [sqlite3_c
368e0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
368f0 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  2()]..*/.#define
36900 20 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e   SQLITE_DETERMIN
36910 49 53 54 49 43 20 20 20 20 30 78 38 30 30 0a 0a  ISTIC    0x800..
36920 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
36930 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 74  Deprecated Funct
36940 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54  ions.** DEPRECAT
36950 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  ED.**.** These f
36960 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65  unctions are [de
36970 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f  precated].  In o
36980 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e  rder to maintain
36990 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f  .** backwards co
369a0 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68  mpatibility with
369b0 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65   older code, the
369c0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e  se functions con
369d0 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20  tinue .** to be 
369e0 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65  supported.  Howe
369f0 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61  ver, new applica
36a00 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f  tions should avo
36a10 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66  id.** the use of
36a20 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
36a30 2e 20 20 54 6f 20 65 6e 63 6f 75 72 61 67 65 20  .  To encourage 
36a40 70 72 6f 67 72 61 6d 6d 65 72 73 20 74 6f 20 61  programmers to a
36a50 76 6f 69 64 0a 2a 2a 20 74 68 65 73 65 20 66 75  void.** these fu
36a60 6e 63 74 69 6f 6e 73 2c 20 77 65 20 77 69 6c 6c  nctions, we will
36a70 20 6e 6f 74 20 65 78 70 6c 61 69 6e 20 77 68 61   not explain wha
36a80 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69  t they do..*/.#i
36a90 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  fndef SQLITE_OMI
36aa0 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c  T_DEPRECATED.SQL
36ab0 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44  ITE_API SQLITE_D
36ac0 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 53 51  EPRECATED int SQ
36ad0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
36ae0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
36af0 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ount(sqlite3_con
36b00 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  text*);.SQLITE_A
36b10 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43  PI SQLITE_DEPREC
36b20 41 54 45 44 20 69 6e 74 20 53 51 4c 49 54 45 5f  ATED int SQLITE_
36b30 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
36b40 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f  expired(sqlite3_
36b50 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  stmt*);.SQLITE_A
36b60 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43  PI SQLITE_DEPREC
36b70 41 54 45 44 20 69 6e 74 20 53 51 4c 49 54 45 5f  ATED int SQLITE_
36b80 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
36b90 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67  transfer_binding
36ba0 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
36bb0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b   sqlite3_stmt*);
36bc0 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
36bd0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
36be0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
36bf0 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f   sqlite3_global_
36c00 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53  recover(void);.S
36c10 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
36c20 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64  _DEPRECATED void
36c30 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
36c40 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63  sqlite3_thread_c
36c50 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51  leanup(void);.SQ
36c60 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
36c70 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 53  DEPRECATED int S
36c80 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
36c90 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61  lite3_memory_ala
36ca0 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  rm(void(*)(void*
36cb0 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69  ,sqlite3_int64,i
36cc0 6e 74 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20  nt),.           
36cd0 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 2a             void*
36ce0 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b  ,sqlite3_int64);
36cf0 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
36d00 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69  API3REF: Obtaini
36d10 6e 67 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a  ng SQL Values.**
36d20 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
36d30 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65  _value.**.** The
36d40 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c   C-language impl
36d50 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51  ementation of SQ
36d60 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
36d70 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a  aggregates uses.
36d80 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69  ** this set of i
36d90 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65  nterface routine
36da0 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
36db0 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73  parameter values
36dc0 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74   on.** the funct
36dd0 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
36de0 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  .  .**.** The xF
36df0 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20  unc (for scalar 
36e00 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53  functions) or xS
36e10 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61  tep (for aggrega
36e20 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a  tes) parameters.
36e30 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
36e40 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
36e50 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
36e60 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
36e70 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61  ()].** define ca
36e80 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70  llbacks that imp
36e90 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
36ea0 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
36eb0 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20  regates..** The 
36ec0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
36ed0 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73   these callbacks
36ee0 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
36ef0 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b  pointers to.** [
36f00 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
36f10 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
36f20 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20  .  There is one 
36f30 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
36f40 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61  object for.** ea
36f50 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ch parameter to 
36f60 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
36f70 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
36f80 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a  s are used to.**
36f90 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20   extract values 
36fa0 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
36fb0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
36fc0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
36fd0 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79  utines work only
36fe0 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64   with [protected
36ff0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
37000 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20  objects..** Any 
37010 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
37020 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
37030 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64   an [unprotected
37040 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a   sqlite3_value].
37050 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74  ** object result
37060 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  s in undefined b
37070 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e  ehavior..**.** ^
37080 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
37090 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68  ork just like th
370a0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
370b0 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  [column access f
370c0 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63  unctions].** exc
370d0 65 70 74 20 74 68 61 74 20 74 68 65 73 65 20 72  ept that these r
370e0 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73  outines take a s
370f0 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64  ingle [protected
37100 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
37110 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65  object.** pointe
37120 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b  r instead of a [
37130 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70  sqlite3_stmt*] p
37140 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e  ointer and an in
37150 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d  teger column num
37160 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ber..**.** ^The 
37170 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
37180 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65  xt16() interface
37190 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d   extracts a UTF-
371a0 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20  16 string.** in 
371b0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d  the native byte-
371c0 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73  order of the hos
371d0 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65  t machine.  ^The
371e0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
371f0 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64  e_text16be() and
37200 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
37210 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66  ext16le() interf
37220 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20  aces.** extract 
37230 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61  UTF-16 strings a
37240 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64  s big-endian and
37250 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72   little-endian r
37260 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a  espectively..**.
37270 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
37280 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
37290 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ype() interface 
372a0 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c  attempts to appl
372b0 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66  y.** numeric aff
372c0 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c  inity to the val
372d0 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20  ue.  This means 
372e0 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20  that an attempt 
372f0 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f  is.** made to co
37300 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
37310 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72  to an integer or
37320 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e   floating point.
37330 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63    If.** such a c
37340 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73  onversion is pos
37350 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f  sible without lo
37360 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f  ss of informatio
37370 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77  n (in other.** w
37380 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c  ords, if the val
37390 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74  ue is a string t
373a0 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61  hat looks like a
373b0 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e   number).** then
373c0 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20   the conversion 
373d0 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f  is performed.  O
373e0 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76  therwise no conv
373f0 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a  ersion occurs..*
37400 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e  * The [SQLITE_IN
37410 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
37420 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69  ] after conversi
37430 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  on is returned.)
37440 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70  ^.**.** Please p
37450 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74  ay particular at
37460 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66  tention to the f
37470 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69  act that the poi
37480 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  nter returned.**
37490 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76   from [sqlite3_v
374a0 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  alue_blob()], [s
374b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
374c0 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  t()], or.** [sql
374d0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
374e0 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61  6()] can be inva
374f0 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62  lidated by a sub
37500 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a  sequent call to.
37510 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
37520 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c  e_bytes()], [sql
37530 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
37540 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  16()], [sqlite3_
37550 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
37560 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
37570 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a  lue_text16()]..*
37580 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
37590 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
375a0 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
375b0 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68   thread as.** th
375c0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
375d0 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65  hat supplied the
375e0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a   [sqlite3_value*
375f0 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f  ] parameters..*/
37600 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
37610 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53  t void *SQLITE_S
37620 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76  TDCALL sqlite3_v
37630 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65  alue_blob(sqlite
37640 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
37650 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
37660 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
37670 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c  _value_bytes(sql
37680 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
37690 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
376a0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
376b0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
376c0 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
376d0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f  );.SQLITE_API do
376e0 75 62 6c 65 20 53 51 4c 49 54 45 5f 53 54 44 43  uble SQLITE_STDC
376f0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ALL sqlite3_valu
37700 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  e_double(sqlite3
37710 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
37720 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
37730 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
37740 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65  value_int(sqlite
37750 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
37760 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e  E_API sqlite3_in
37770 74 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41  t64 SQLITE_STDCA
37780 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  LL sqlite3_value
37790 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76  _int64(sqlite3_v
377a0 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
377b0 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  PI const unsigne
377c0 64 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53  d char *SQLITE_S
377d0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76  TDCALL sqlite3_v
377e0 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65  alue_text(sqlite
377f0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
37800 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
37810 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
37820 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
37830 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61  ext16(sqlite3_va
37840 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
37850 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51  I const void *SQ
37860 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
37870 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
37880 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6le(sqlite3_valu
37890 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
378a0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49  const void *SQLI
378b0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
378c0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
378d0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
378e0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
378f0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
37900 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
37910 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
37920 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
37930 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
37940 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  LL sqlite3_value
37950 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71  _numeric_type(sq
37960 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a  lite3_value*);..
37970 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37980 46 69 6e 64 69 6e 67 20 54 68 65 20 53 75 62 74  Finding The Subt
37990 79 70 65 20 4f 66 20 53 51 4c 20 56 61 6c 75 65  ype Of SQL Value
379a0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
379b0 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a  ite3_value.**.**
379c0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   The sqlite3_val
379d0 75 65 5f 73 75 62 74 79 70 65 28 56 29 20 66 75  ue_subtype(V) fu
379e0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
379f0 68 65 20 73 75 62 74 79 70 65 20 66 6f 72 0a 2a  he subtype for.*
37a00 2a 20 61 6e 20 5b 61 70 70 6c 69 63 61 74 69 6f  * an [applicatio
37a10 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
37a20 6e 63 74 69 6f 6e 5d 20 61 72 67 75 6d 65 6e 74  nction] argument
37a30 20 56 2e 20 20 54 68 65 20 73 75 62 74 79 70 65   V.  The subtype
37a40 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
37a50 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 70  can be used to p
37a60 61 73 73 20 61 20 6c 69 6d 69 74 65 64 20 61 6d  ass a limited am
37a70 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 78 74 20  ount of context 
37a80 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 53 51 4c 20  from.** one SQL 
37a90 66 75 6e 63 74 69 6f 6e 20 74 6f 20 61 6e 6f 74  function to anot
37aa0 68 65 72 2e 20 20 55 73 65 20 74 68 65 20 5b 73  her.  Use the [s
37ab0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 73 75  qlite3_result_su
37ac0 62 74 79 70 65 28 29 5d 0a 2a 2a 20 72 6f 75 74  btype()].** rout
37ad0 69 6e 65 20 74 6f 20 73 65 74 20 74 68 65 20 73  ine to set the s
37ae0 75 62 74 79 70 65 20 66 6f 72 20 74 68 65 20 72  ubtype for the r
37af0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 61  eturn value of a
37b00 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a  n SQL function..
37b10 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b  **.** SQLite mak
37b20 65 73 20 6e 6f 20 75 73 65 20 6f 66 20 73 75 62  es no use of sub
37b30 74 79 70 65 20 69 74 73 65 6c 66 2e 20 20 49 74  type itself.  It
37b40 20 6d 65 72 65 6c 79 20 70 61 73 73 65 73 20 74   merely passes t
37b50 68 65 20 73 75 62 74 79 70 65 0a 2a 2a 20 66 72  he subtype.** fr
37b60 6f 6d 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  om the result of
37b70 20 6f 6e 65 20 5b 61 70 70 6c 69 63 61 74 69 6f   one [applicatio
37b80 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
37b90 6e 63 74 69 6f 6e 5d 20 69 6e 74 6f 20 74 68 65  nction] into the
37ba0 0a 2a 2a 20 69 6e 70 75 74 20 6f 66 20 61 6e 6f  .** input of ano
37bb0 74 68 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ther..*/.SQLITE_
37bc0 41 50 49 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  API unsigned int
37bd0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
37be0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 73 75  sqlite3_value_su
37bf0 62 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61  btype(sqlite3_va
37c00 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  lue*);../*.** CA
37c10 50 49 33 52 45 46 3a 20 43 6f 70 79 20 41 6e 64  PI3REF: Copy And
37c20 20 46 72 65 65 20 53 51 4c 20 56 61 6c 75 65 73   Free SQL Values
37c30 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
37c40 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20  te3_value.**.** 
37c50 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
37c60 75 65 5f 64 75 70 28 56 29 20 69 6e 74 65 72 66  ue_dup(V) interf
37c70 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ace makes a copy
37c80 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
37c90 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63  _value].** objec
37ca0 74 20 44 20 61 6e 64 20 72 65 74 75 72 6e 73 20  t D and returns 
37cb0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61  a pointer to tha
37cc0 74 20 63 6f 70 79 2e 20 20 5e 54 68 65 20 5b 73  t copy.  ^The [s
37cd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 72 65  qlite3_value] re
37ce0 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 61 20 5b  turned.** is a [
37cf0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
37d00 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
37d10 65 76 65 6e 20 69 66 20 74 68 65 20 69 6e 70 75  even if the inpu
37d20 74 20 69 73 20 6e 6f 74 2e 0a 2a 2a 20 5e 54 68  t is not..** ^Th
37d30 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
37d40 64 75 70 28 56 29 20 69 6e 74 65 72 66 61 63 65  dup(V) interface
37d50 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66   returns NULL if
37d60 20 56 20 69 73 20 4e 55 4c 4c 20 6f 72 20 69 66   V is NULL or if
37d70 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c   a.** memory all
37d80 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2e 0a 2a  ocation fails..*
37d90 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
37da0 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 56 29 20  3_value_free(V) 
37db0 69 6e 74 65 72 66 61 63 65 20 66 72 65 65 73 20  interface frees 
37dc0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  an [sqlite3_valu
37dd0 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 72 65  e] object.** pre
37de0 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64  viously obtained
37df0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76   from [sqlite3_v
37e00 61 6c 75 65 5f 64 75 70 28 29 5d 2e 20 20 5e 49  alue_dup()].  ^I
37e10 66 20 56 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f V is a NULL po
37e20 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6e 20 73 71  inter.** then sq
37e30 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65  lite3_value_free
37e40 28 56 29 20 69 73 20 61 20 68 61 72 6d 6c 65 73  (V) is a harmles
37e50 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49  s no-op..*/.SQLI
37e60 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 76  TE_API sqlite3_v
37e70 61 6c 75 65 20 2a 53 51 4c 49 54 45 5f 53 54 44  alue *SQLITE_STD
37e80 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c  CALL sqlite3_val
37e90 75 65 5f 64 75 70 28 63 6f 6e 73 74 20 73 71 6c  ue_dup(const sql
37ea0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
37eb0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51  LITE_API void SQ
37ec0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
37ed0 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28  ite3_value_free(
37ee0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
37ef0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
37f00 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61  : Obtain Aggrega
37f10 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  te Function Cont
37f20 65 78 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ext.** METHOD: s
37f30 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a  qlite3_context.*
37f40 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74  *.** Implementat
37f50 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74  ions of aggregat
37f60 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
37f70 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74  use this.** rout
37f80 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ine to allocate 
37f90 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69  memory for stori
37fa0 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a  ng their state..
37fb0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
37fc0 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65   time the sqlite
37fd0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
37fe0 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65  ext(C,N) routine
37ff0 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66   is called .** f
38000 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
38010 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
38020 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c  on, SQLite.** al
38030 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d  locates N of mem
38040 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20  ory, zeroes out 
38050 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64  that memory, and
38060 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
38070 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77  er.** to the new
38080 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63   memory. ^On sec
38090 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
380a0 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73  nt calls to.** s
380b0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
380c0 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74  _context() for t
380d0 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74  he same aggregat
380e0 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61  e function insta
380f0 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65  nce,.** the same
38100 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72   buffer is retur
38110 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67  ned.  Sqlite3_ag
38120 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
38130 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a  ) is normally.**
38140 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72   called once for
38150 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e   each invocation
38160 20 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 61   of the xStep ca
38170 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20  llback and then 
38180 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65  one.** last time
38190 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c   when the xFinal
381a0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
381b0 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f  oked.  ^(When no
381c0 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61   rows match.** a
381d0 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72  n aggregate quer
381e0 79 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 63  y, the xStep() c
381f0 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61  allback of the a
38200 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
38210 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n.** implementat
38220 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c  ion is never cal
38230 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29  led and xFinal()
38240 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74   is called exact
38250 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74  ly once..** In t
38260 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69  hose cases, sqli
38270 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
38280 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 65  ntext() might be
38290 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a   called for the.
382a0 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 72  ** first time fr
382b0 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c  om within xFinal
382c0 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().)^.**.** ^The
382d0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
382e0 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
382f0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
38300 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a  a NULL pointer .
38310 2a 2a 20 77 68 65 6e 20 66 69 72 73 74 20 63 61  ** when first ca
38320 6c 6c 65 64 20 69 66 20 4e 20 69 73 20 6c 65 73  lled if N is les
38330 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
38340 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20  to zero or if a 
38350 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
38360 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  te error occurs.
38370 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f  .**.** ^(The amo
38380 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c  unt of space all
38390 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  ocated by sqlite
383a0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
383b0 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64  ext(C,N) is.** d
383c0 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65  etermined by the
383d0 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20   N parameter on 
383e0 66 69 72 73 74 20 73 75 63 63 65 73 73 66 75 6c  first successful
383f0 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67   call.  Changing
38400 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66   the.** value of
38410 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74   N in subsequent
38420 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
38430 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
38440 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74  xt() within.** t
38450 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74  he same aggregat
38460 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61  e function insta
38470 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73  nce will not res
38480 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a  ize the memory.*
38490 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20  * allocation.)^ 
384a0 20 57 69 74 68 69 6e 20 74 68 65 20 78 46 69 6e   Within the xFin
384b0 61 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20  al callback, it 
384c0 69 73 20 63 75 73 74 6f 6d 61 72 79 20 74 6f 20  is customary to 
384d0 73 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61  set.** N=0 in ca
384e0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 61  lls to sqlite3_a
384f0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
38500 28 43 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e 6f  (C,N) so that no
38510 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20 6d   .** pointless m
38520 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
38530 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e  s occur..**.** ^
38540 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63  SQLite automatic
38550 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d  ally frees the m
38560 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20  emory allocated 
38570 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61  by .** sqlite3_a
38580 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
38590 28 29 20 77 68 65 6e 20 74 68 65 20 61 67 67 72  () when the aggr
385a0 65 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63  egate query conc
385b0 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ludes..**.** The
385c0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
385d0 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79 20   must be a copy 
385e0 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
385f0 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c  e3_context | SQL
38600 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78   function contex
38610 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66  t] that is the f
38620 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a  irst parameter.*
38630 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f  * to the xStep o
38640 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  r xFinal callbac
38650 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69  k routine that i
38660 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67  mplements the ag
38670 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74  gregate.** funct
38680 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
38690 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
386a0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
386b0 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
386c0 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72  hich.** the aggr
386d0 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
386e0 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
386f0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
38700 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  d *SQLITE_STDCAL
38710 4c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  L sqlite3_aggreg
38720 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69  ate_context(sqli
38730 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
38740 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a  t nBytes);../*.*
38750 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72  * CAPI3REF: User
38760 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69   Data For Functi
38770 6f 6e 73