System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 234a3275d03a287434ace3ccdf1afb208e6b0e92:


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 34 2e 30 2e 20 20  ersion 3.14.0.  
00b0: 42 79 20 63 6f 6d 62 69 6e 69 6e 67 20 61 6c 6c  By combining all
00c0: 20 74 68 65 20 69 6e 64 69 76 69 64 75 61 6c 20   the individual 
00d0: 43 20 63 6f 64 65 20 66 69 6c 65 73 20 69 6e 74  C code files int
00e0: 6f 20 74 68 69 73 20 0a 2a 2a 20 73 69 6e 67 6c  o this .** singl
00f0: 65 20 6c 61 72 67 65 20 66 69 6c 65 2c 20 74 68  e large file, th
0100: 65 20 65 6e 74 69 72 65 20 63 6f 64 65 20 63 61  e entire code ca
0110: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 61 73  n be compiled as
0120: 20 61 20 73 69 6e 67 6c 65 20 74 72 61 6e 73 6c   a single transl
0130: 61 74 69 6f 6e 0a 2a 2a 20 75 6e 69 74 2e 20 20  ation.** unit.  
0140: 54 68 69 73 20 61 6c 6c 6f 77 73 20 6d 61 6e 79  This allows many
0150: 20 63 6f 6d 70 69 6c 65 72 73 20 74 6f 20 64 6f   compilers to do
0160: 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 74   optimizations t
0170: 68 61 74 20 77 6f 75 6c 64 20 6e 6f 74 20 62 65  hat would not be
0180: 0a 2a 2a 20 70 6f 73 73 69 62 6c 65 20 69 66 20  .** possible if 
0190: 74 68 65 20 66 69 6c 65 73 20 77 65 72 65 20 63  the files were c
01a0: 6f 6d 70 69 6c 65 64 20 73 65 70 61 72 61 74 65  ompiled separate
01b0: 6c 79 2e 20 20 50 65 72 66 6f 72 6d 61 6e 63 65  ly.  Performance
01c0: 20 69 6d 70 72 6f 76 65 6d 65 6e 74 73 0a 2a 2a   improvements.**
01d0: 20 6f 66 20 35 25 20 6f 72 20 6d 6f 72 65 20 61   of 5% or more a
01e0: 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 73 65 65 6e  re commonly seen
01f0: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
0200: 63 6f 6d 70 69 6c 65 64 20 61 73 20 61 20 73 69  compiled as a si
0210: 6e 67 6c 65 0a 2a 2a 20 74 72 61 6e 73 6c 61 74  ngle.** translat
0220: 69 6f 6e 20 75 6e 69 74 2e 0a 2a 2a 0a 2a 2a 20  ion unit..**.** 
0230: 54 68 69 73 20 66 69 6c 65 20 69 73 20 61 6c 6c  This file is all
0240: 20 79 6f 75 20 6e 65 65 64 20 74 6f 20 63 6f 6d   you need to com
0250: 70 69 6c 65 20 53 51 4c 69 74 65 2e 20 20 54 6f  pile SQLite.  To
0260: 20 75 73 65 20 53 51 4c 69 74 65 20 69 6e 20 6f   use SQLite in o
0270: 74 68 65 72 0a 2a 2a 20 70 72 6f 67 72 61 6d 73  ther.** programs
0280: 2c 20 79 6f 75 20 6e 65 65 64 20 74 68 69 73 20  , you need this 
0290: 66 69 6c 65 20 61 6e 64 20 74 68 65 20 22 73 71  file and the "sq
02a0: 6c 69 74 65 33 2e 68 22 20 68 65 61 64 65 72 20  lite3.h" header 
02b0: 66 69 6c 65 20 74 68 61 74 20 64 65 66 69 6e 65  file that define
02c0: 73 0a 2a 2a 20 74 68 65 20 70 72 6f 67 72 61 6d  s.** the program
02d0: 6d 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 74  ming interface t
02e0: 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  o the SQLite lib
02f0: 72 61 72 79 2e 20 20 28 49 66 20 79 6f 75 20 64  rary.  (If you d
0300: 6f 20 6e 6f 74 20 68 61 76 65 20 0a 2a 2a 20 74  o not have .** t
0310: 68 65 20 22 73 71 6c 69 74 65 33 2e 68 22 20 68  he "sqlite3.h" h
0320: 65 61 64 65 72 20 66 69 6c 65 20 61 74 20 68 61  eader file at ha
0330: 6e 64 2c 20 79 6f 75 20 77 69 6c 6c 20 66 69 6e  nd, you will fin
0340: 64 20 61 20 63 6f 70 79 20 65 6d 62 65 64 64 65  d a copy embedde
0350: 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  d within.** the 
0360: 74 65 78 74 20 6f 66 20 74 68 69 73 20 66 69 6c  text of this fil
0370: 65 2e 20 20 53 65 61 72 63 68 20 66 6f 72 20 22  e.  Search for "
0380: 42 65 67 69 6e 20 66 69 6c 65 20 73 71 6c 69 74  Begin file sqlit
0390: 65 33 2e 68 22 20 74 6f 20 66 69 6e 64 20 74 68  e3.h" to find th
03a0: 65 20 73 74 61 72 74 0a 2a 2a 20 6f 66 20 74 68  e start.** of th
03b0: 65 20 65 6d 62 65 64 64 65 64 20 73 71 6c 69 74  e embedded sqlit
03c0: 65 33 2e 68 20 68 65 61 64 65 72 20 66 69 6c 65  e3.h header file
03d0: 2e 29 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 6f  .) Additional co
03e0: 64 65 20 66 69 6c 65 73 20 6d 61 79 20 62 65 20  de files may be 
03f0: 6e 65 65 64 65 64 0a 2a 2a 20 69 66 20 79 6f 75  needed.** if you
0400: 20 77 61 6e 74 20 61 20 77 72 61 70 70 65 72 20   want a wrapper 
0410: 74 6f 20 69 6e 74 65 72 66 61 63 65 20 53 51 4c  to interface SQL
0420: 69 74 65 20 77 69 74 68 20 79 6f 75 72 20 63 68  ite with your ch
0430: 6f 69 63 65 20 6f 66 20 70 72 6f 67 72 61 6d 6d  oice of programm
0440: 69 6e 67 0a 2a 2a 20 6c 61 6e 67 75 61 67 65 2e  ing.** language.
0450: 20 54 68 65 20 63 6f 64 65 20 66 6f 72 20 74 68   The code for th
0460: 65 20 22 73 71 6c 69 74 65 33 22 20 63 6f 6d 6d  e "sqlite3" comm
0470: 61 6e 64 2d 6c 69 6e 65 20 73 68 65 6c 6c 20 69  and-line shell i
0480: 73 20 61 6c 73 6f 20 69 6e 20 61 0a 2a 2a 20 73  s also in a.** s
0490: 65 70 61 72 61 74 65 20 66 69 6c 65 2e 20 54 68  eparate file. Th
04a0: 69 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73  is file contains
04b0: 20 6f 6e 6c 79 20 63 6f 64 65 20 66 6f 72 20 74   only code for t
04c0: 68 65 20 63 6f 72 65 20 53 51 4c 69 74 65 20 6c  he core SQLite l
04d0: 69 62 72 61 72 79 2e 0a 2a 2f 0a 23 64 65 66 69  ibrary..*/.#defi
04e0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 45 20 31  ne SQLITE_CORE 1
04f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
0500: 41 4d 41 4c 47 41 4d 41 54 49 4f 4e 20 31 0a 23  AMALGAMATION 1.#
0510: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 50 52  ifndef SQLITE_PR
0520: 49 56 41 54 45 0a 23 20 64 65 66 69 6e 65 20 53  IVATE.# define S
0530: 51 4c 49 54 45 5f 50 52 49 56 41 54 45 20 73 74  QLITE_PRIVATE st
0540: 61 74 69 63 0a 23 65 6e 64 69 66 0a 2f 2a 2a 2a  atic.#endif./***
0550: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69  *********** Begi
0560: 6e 20 66 69 6c 65 20 73 71 6c 69 74 65 49 6e 74  n file sqliteInt
0570: 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  .h *************
0580: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0590: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a  **********/./*.*
05a0: 2a 20 32 30 30 31 20 53 65 70 74 65 6d 62 65 72  * 2001 September
05b0: 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75   15.**.** The au
05c0: 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63  thor disclaims c
05d0: 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73  opyright to this
05e0: 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49   source code.  I
05f0: 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20  n place of.** a 
0600: 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65  legal notice, he
0610: 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67  re is a blessing
0620: 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79  :.**.**    May y
0630: 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e  ou do good and n
0640: 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d  ot evil..**    M
0650: 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67  ay you find forg
0660: 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72  iveness for your
0670: 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65  self and forgive
0680: 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d   others..**    M
0690: 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65  ay you share fre
06a0: 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e  ely, never takin
06b0: 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20  g more than you 
06c0: 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a  give..**.*******
06d0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
06e0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
06f0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0700: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0710: 2a 2a 0a 2a 2a 20 49 6e 74 65 72 6e 61 6c 20 69  **.** Internal i
0720: 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 69 74  nterface definit
0730: 69 6f 6e 73 20 66 6f 72 20 53 51 4c 69 74 65 2e  ions for SQLite.
0740: 0a 2a 2a 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  .**.*/.#ifndef S
0750: 51 4c 49 54 45 49 4e 54 5f 48 0a 23 64 65 66 69  QLITEINT_H.#defi
0760: 6e 65 20 53 51 4c 49 54 45 49 4e 54 5f 48 0a 0a  ne SQLITEINT_H..
0770: 2f 2a 20 53 70 65 63 69 61 6c 20 43 6f 6d 6d 65  /* Special Comme
0780: 6e 74 73 3a 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20  nts:.**.** Some 
0790: 63 6f 6d 6d 65 6e 74 73 20 68 61 76 65 20 73 70  comments have sp
07a0: 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f  ecial meaning to
07b0: 20 74 68 65 20 74 6f 6f 6c 73 20 74 68 61 74 20   the tools that 
07c0: 6d 65 61 73 75 72 65 20 74 65 73 74 0a 2a 2a 20  measure test.** 
07d0: 63 6f 76 65 72 61 67 65 3a 0a 2a 2a 0a 2a 2a 20  coverage:.**.** 
07e0: 20 20 20 4e 4f 5f 54 45 53 54 20 20 20 20 20 20     NO_TEST      
07f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2d                 -
0800: 20 54 68 65 20 62 72 61 6e 63 68 65 73 20 6f 6e   The branches on
0810: 20 74 68 69 73 20 6c 69 6e 65 20 61 72 65 20 6e   this line are n
0820: 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ot.**           
0830: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
0840: 20 20 20 20 20 20 20 6d 65 61 73 75 72 65 64 20         measured 
0850: 62 79 20 62 72 61 6e 63 68 20 63 6f 76 65 72 61  by branch covera
0860: 67 65 2e 20 20 54 68 69 73 20 69 73 0a 2a 2a 20  ge.  This is.** 
0870: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
0880: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
0890: 20 75 73 65 64 20 6f 6e 20 6c 69 6e 65 73 20 6f   used on lines o
08a0: 66 20 63 6f 64 65 20 74 68 61 74 20 61 63 74 75  f code that actu
08b0: 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  ally.**         
08c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
08d0: 20 20 20 20 20 20 20 20 20 69 6d 70 6c 65 6d 65           impleme
08e0: 6e 74 20 70 61 72 74 73 20 6f 66 20 63 6f 76 65  nt parts of cove
08f0: 72 61 67 65 20 74 65 73 74 69 6e 67 2e 0a 2a 2a  rage testing..**
0900: 0a 2a 2a 20 20 20 20 4f 50 54 49 4d 49 5a 41 54  .**    OPTIMIZAT
0910: 49 4f 4e 2d 49 46 2d 54 52 55 45 20 20 20 20 20  ION-IF-TRUE     
0920: 20 20 20 2d 20 54 68 69 73 20 62 72 61 6e 63 68     - This branch
0930: 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 61   is allowed to a
0940: 6c 77 61 79 20 62 65 20 66 61 6c 73 65 0a 2a 2a  lway be false.**
0950: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
0960: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
0970: 20 20 61 6e 64 20 74 68 65 20 63 6f 72 72 65 63    and the correc
0980: 74 20 61 6e 73 77 65 72 20 69 73 20 73 74 69 6c  t answer is stil
0990: 6c 20 6f 62 74 61 69 6e 65 64 2c 0a 2a 2a 20 20  l obtained,.**  
09a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
09b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
09c0: 74 68 6f 75 67 68 20 70 65 72 68 61 70 73 20 6d  though perhaps m
09d0: 6f 72 65 20 73 6c 6f 77 6c 79 2e 0a 2a 2a 0a 2a  ore slowly..**.*
09e0: 2a 20 20 20 20 4f 50 54 49 4d 49 5a 41 54 49 4f  *    OPTIMIZATIO
09f0: 4e 2d 49 46 2d 46 41 4c 53 45 20 20 20 20 20 20  N-IF-FALSE      
0a00: 20 2d 20 54 68 69 73 20 62 72 61 6e 63 68 20 69   - This branch i
0a10: 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 61 6c 77  s allowed to alw
0a20: 61 79 20 62 65 20 74 72 75 65 0a 2a 2a 20 20 20  ay be true.**   
0a30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
0a40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 61                 a
0a50: 6e 64 20 74 68 65 20 63 6f 72 72 65 63 74 20 61  nd the correct a
0a60: 6e 73 77 65 72 20 69 73 20 73 74 69 6c 6c 20 6f  nswer is still o
0a70: 62 74 61 69 6e 65 64 2c 0a 2a 2a 20 20 20 20 20  btained,.**     
0a80: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
0a90: 20 20 20 20 20 20 20 20 20 20 20 20 20 74 68 6f               tho
0aa0: 75 67 68 20 70 65 72 68 61 70 73 20 6d 6f 72 65  ugh perhaps more
0ab0: 20 73 6c 6f 77 6c 79 2e 0a 2a 2a 0a 2a 2a 20 20   slowly..**.**  
0ac0: 20 20 50 52 45 56 45 4e 54 53 2d 48 41 52 4d 4c    PREVENTS-HARML
0ad0: 45 53 53 2d 4f 56 45 52 52 45 41 44 20 20 2d 20  ESS-OVERREAD  - 
0ae0: 54 68 69 73 20 62 72 61 6e 63 68 20 70 72 65 76  This branch prev
0af0: 65 6e 74 73 20 61 20 62 75 66 66 65 72 20 6f 76  ents a buffer ov
0b00: 65 72 72 65 61 64 0a 2a 2a 20 20 20 20 20 20 20  erread.**       
0b10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
0b20: 20 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20             that 
0b30: 77 6f 75 6c 64 20 62 65 20 68 61 72 6d 6c 65 73  would be harmles
0b40: 73 20 61 6e 64 20 75 6e 64 65 74 65 63 74 61 62  s and undetectab
0b50: 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  le.**           
0b60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
0b70: 20 20 20 20 20 20 20 69 66 20 69 74 20 64 69 64         if it did
0b80: 20 6f 63 63 75 72 2e 20 20 0a 2a 2a 0a 2a 2a 20   occur.  .**.** 
0b90: 49 6e 20 61 6c 6c 20 63 61 73 65 73 2c 20 74 68  In all cases, th
0ba0: 65 20 73 70 65 63 69 61 6c 20 63 6f 6d 6d 65 6e  e special commen
0bb0: 74 20 6d 75 73 74 20 62 65 20 65 6e 63 6c 6f 73  t must be enclos
0bc0: 65 64 20 69 6e 20 74 68 65 20 75 73 75 61 6c 0a  ed in the usual.
0bd0: 2a 2a 20 73 6c 61 73 68 2d 61 73 74 65 72 69 73  ** slash-asteris
0be0: 6b 2e 2e 2e 61 73 74 65 72 69 73 6b 2d 73 6c 61  k...asterisk-sla
0bf0: 73 68 20 63 6f 6d 6d 65 6e 74 20 6d 61 72 6b 73  sh comment marks
0c00: 2c 20 77 69 74 68 20 6e 6f 20 73 70 61 63 65 73  , with no spaces
0c10: 20 62 65 74 77 65 65 6e 20 74 68 65 20 0a 2a 2a   between the .**
0c20: 20 61 73 74 65 72 69 73 6b 73 20 61 6e 64 20 74   asterisks and t
0c30: 68 65 20 63 6f 6d 6d 65 6e 74 20 74 65 78 74 2e  he comment text.
0c40: 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20  .*/../*.** Make 
0c50: 73 75 72 65 20 74 68 65 20 54 63 6c 20 63 61 6c  sure the Tcl cal
0c60: 6c 69 6e 67 20 63 6f 6e 76 65 6e 74 69 6f 6e 20  ling convention 
0c70: 6d 61 63 72 6f 20 69 73 20 64 65 66 69 6e 65 64  macro is defined
0c80: 2e 20 20 54 68 69 73 20 6d 61 63 72 6f 20 69 73  .  This macro is
0c90: 0a 2a 2a 20 6f 6e 6c 79 20 75 73 65 64 20 62 79  .** only used by
0ca0: 20 74 65 73 74 20 63 6f 64 65 20 61 6e 64 20 54   test code and T
0cb0: 63 6c 20 69 6e 74 65 67 72 61 74 69 6f 6e 20 63  cl integration c
0cc0: 6f 64 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20  ode..*/.#ifndef 
0cd0: 53 51 4c 49 54 45 5f 54 43 4c 41 50 49 0a 23 20  SQLITE_TCLAPI.# 
0ce0: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54   define SQLITE_T
0cf0: 43 4c 41 50 49 0a 23 65 6e 64 69 66 0a 0a 2f 2a  CLAPI.#endif../*
0d00: 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 74 68  .** Make sure th
0d10: 61 74 20 72 61 6e 64 5f 73 28 29 20 69 73 20 61  at rand_s() is a
0d20: 76 61 69 6c 61 62 6c 65 20 6f 6e 20 57 69 6e 64  vailable on Wind
0d30: 6f 77 73 20 73 79 73 74 65 6d 73 20 77 69 74 68  ows systems with
0d40: 20 4d 53 56 43 20 32 30 30 35 0a 2a 2a 20 6f 72   MSVC 2005.** or
0d50: 20 68 69 67 68 65 72 2e 0a 2a 2f 0a 23 69 66 20   higher..*/.#if 
0d60: 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52  defined(_MSC_VER
0d70: 29 20 26 26 20 5f 4d 53 43 5f 56 45 52 3e 3d 31  ) && _MSC_VER>=1
0d80: 34 30 30 0a 23 20 20 64 65 66 69 6e 65 20 5f 43  400.#  define _C
0d90: 52 54 5f 52 41 4e 44 5f 53 0a 23 65 6e 64 69 66  RT_RAND_S.#endif
0da0: 0a 0a 2f 2a 0a 2a 2a 20 49 6e 63 6c 75 64 65 20  ../*.** Include 
0db0: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 20  the header file 
0dc0: 75 73 65 64 20 74 6f 20 63 75 73 74 6f 6d 69 7a  used to customiz
0dd0: 65 20 74 68 65 20 63 6f 6d 70 69 6c 65 72 20 6f  e the compiler o
0de0: 70 74 69 6f 6e 73 20 66 6f 72 20 4d 53 56 43 2e  ptions for MSVC.
0df0: 0a 2a 2a 20 54 68 69 73 20 73 68 6f 75 6c 64 20  .** This should 
0e00: 62 65 20 64 6f 6e 65 20 66 69 72 73 74 20 73 6f  be done first so
0e10: 20 74 68 61 74 20 69 74 20 63 61 6e 20 73 75 63   that it can suc
0e20: 63 65 73 73 66 75 6c 6c 79 20 70 72 65 76 65 6e  cessfully preven
0e30: 74 20 73 70 75 72 69 6f 75 73 0a 2a 2a 20 63 6f  t spurious.** co
0e40: 6d 70 69 6c 65 72 20 77 61 72 6e 69 6e 67 73 20  mpiler warnings 
0e50: 64 75 65 20 74 6f 20 73 75 62 73 65 71 75 65 6e  due to subsequen
0e60: 74 20 63 6f 6e 74 65 6e 74 20 69 6e 20 74 68 69  t content in thi
0e70: 73 20 66 69 6c 65 20 61 6e 64 20 6f 74 68 65 72  s file and other
0e80: 20 66 69 6c 65 73 0a 2a 2a 20 74 68 61 74 20 61   files.** that a
0e90: 72 65 20 69 6e 63 6c 75 64 65 64 20 62 79 20 74  re included by t
0ea0: 68 69 73 20 66 69 6c 65 2e 0a 2a 2f 0a 2f 2a 2a  his file..*/./**
0eb0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 49 6e 63  ************ Inc
0ec0: 6c 75 64 65 20 6d 73 76 63 2e 68 20 69 6e 20 74  lude msvc.h in t
0ed0: 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 73 71 6c  he middle of sql
0ee0: 69 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a  iteInt.h *******
0ef0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a  ***********/./**
0f00: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67  ************ Beg
0f10: 69 6e 20 66 69 6c 65 20 6d 73 76 63 2e 68 20 2a  in file msvc.h *
0f20: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0f30: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0f40: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a  ***********/./*.
0f50: 2a 2a 20 32 30 31 35 20 4a 61 6e 75 61 72 79 20  ** 2015 January 
0f60: 31 32 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74  12.**.** The aut
0f70: 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f  hor disclaims co
0f80: 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73 20  pyright to this 
0f90: 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e  source code.  In
0fa0: 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c   place of.** a l
0fb0: 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72  egal notice, her
0fc0: 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a  e is a blessing:
0fd0: 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f  .**.**    May yo
0fe0: 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f  u do good and no
0ff0: 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61  t evil..**    Ma
1000: 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69  y you find forgi
1010: 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73  veness for yours
1020: 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20  elf and forgive 
1030: 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61  others..**    Ma
1040: 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65 65  y you share free
1050: 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67  ly, never taking
1060: 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67   more than you g
1070: 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a  ive..**.********
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: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
10b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
10c0: 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 69  ******.**.** Thi
10d0: 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73 20  s file contains 
10e0: 63 6f 64 65 20 74 68 61 74 20 69 73 20 73 70 65  code that is spe
10f0: 63 69 66 69 63 20 74 6f 20 4d 53 56 43 2e 0a 2a  cific to MSVC..*
1100: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
1110: 5f 4d 53 56 43 5f 48 0a 23 64 65 66 69 6e 65 20  _MSVC_H.#define 
1120: 53 51 4c 49 54 45 5f 4d 53 56 43 5f 48 0a 0a 23  SQLITE_MSVC_H..#
1130: 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f  if defined(_MSC_
1140: 56 45 52 29 0a 23 70 72 61 67 6d 61 20 77 61 72  VER).#pragma war
1150: 6e 69 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34  ning(disable : 4
1160: 30 35 34 29 0a 23 70 72 61 67 6d 61 20 77 61 72  054).#pragma war
1170: 6e 69 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34  ning(disable : 4
1180: 30 35 35 29 0a 23 70 72 61 67 6d 61 20 77 61 72  055).#pragma war
1190: 6e 69 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34  ning(disable : 4
11a0: 31 30 30 29 0a 23 70 72 61 67 6d 61 20 77 61 72  100).#pragma war
11b0: 6e 69 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34  ning(disable : 4
11c0: 31 32 37 29 0a 23 70 72 61 67 6d 61 20 77 61 72  127).#pragma war
11d0: 6e 69 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34  ning(disable : 4
11e0: 31 33 30 29 0a 23 70 72 61 67 6d 61 20 77 61 72  130).#pragma war
11f0: 6e 69 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34  ning(disable : 4
1200: 31 35 32 29 0a 23 70 72 61 67 6d 61 20 77 61 72  152).#pragma war
1210: 6e 69 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34  ning(disable : 4
1220: 31 38 39 29 0a 23 70 72 61 67 6d 61 20 77 61 72  189).#pragma war
1230: 6e 69 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34  ning(disable : 4
1240: 32 30 36 29 0a 23 70 72 61 67 6d 61 20 77 61 72  206).#pragma war
1250: 6e 69 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34  ning(disable : 4
1260: 32 31 30 29 0a 23 70 72 61 67 6d 61 20 77 61 72  210).#pragma war
1270: 6e 69 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34  ning(disable : 4
1280: 32 33 32 29 0a 23 70 72 61 67 6d 61 20 77 61 72  232).#pragma war
1290: 6e 69 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34  ning(disable : 4
12a0: 32 34 34 29 0a 23 70 72 61 67 6d 61 20 77 61 72  244).#pragma war
12b0: 6e 69 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34  ning(disable : 4
12c0: 33 30 35 29 0a 23 70 72 61 67 6d 61 20 77 61 72  305).#pragma war
12d0: 6e 69 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34  ning(disable : 4
12e0: 33 30 36 29 0a 23 70 72 61 67 6d 61 20 77 61 72  306).#pragma war
12f0: 6e 69 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34  ning(disable : 4
1300: 37 30 32 29 0a 23 70 72 61 67 6d 61 20 77 61 72  702).#pragma war
1310: 6e 69 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34  ning(disable : 4
1320: 37 30 36 29 0a 23 65 6e 64 69 66 20 2f 2a 20 64  706).#endif /* d
1330: 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29  efined(_MSC_VER)
1340: 20 2a 2f 0a 0a 23 65 6e 64 69 66 20 2f 2a 20 53   */..#endif /* S
1350: 51 4c 49 54 45 5f 4d 53 56 43 5f 48 20 2a 2f 0a  QLITE_MSVC_H */.
1360: 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
1370: 20 45 6e 64 20 6f 66 20 6d 73 76 63 2e 68 20 2a   End of msvc.h *
1380: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1390: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
13a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  ***************/
13b0: 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
13c0: 20 43 6f 6e 74 69 6e 75 69 6e 67 20 77 68 65 72   Continuing wher
13d0: 65 20 77 65 20 6c 65 66 74 20 6f 66 66 20 69 6e  e we left off in
13e0: 20 73 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a   sqliteInt.h ***
13f0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  ***************/
1400: 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 61 6c 20  ../*.** Special 
1410: 73 65 74 75 70 20 66 6f 72 20 56 78 57 6f 72 6b  setup for VxWork
1420: 73 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  s.*/./**********
1430: 2a 2a 2a 2a 20 49 6e 63 6c 75 64 65 20 76 78 77  **** Include vxw
1440: 6f 72 6b 73 2e 68 20 69 6e 20 74 68 65 20 6d 69  orks.h in the mi
1450: 64 64 6c 65 20 6f 66 20 73 71 6c 69 74 65 49 6e  ddle of sqliteIn
1460: 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  t.h ************
1470: 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ***/./**********
1480: 2a 2a 2a 2a 20 42 65 67 69 6e 20 66 69 6c 65 20  **** Begin file 
1490: 76 78 77 6f 72 6b 73 2e 68 20 2a 2a 2a 2a 2a 2a  vxworks.h ******
14a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
14b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
14c0: 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30 31 35 2d  ***/./*.** 2015-
14d0: 30 33 2d 30 32 0a 2a 2a 0a 2a 2a 20 54 68 65 20  03-02.**.** The 
14e0: 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73  author disclaims
14f0: 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68   copyright to th
1500: 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20  is source code. 
1510: 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20   In place of.** 
1520: 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20  a legal notice, 
1530: 68 65 72 65 20 69 73 20 61 20 62 6c 65 73 73 69  here is a blessi
1540: 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79  ng:.**.**    May
1550: 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64   you do good and
1560: 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20   not evil..**   
1570: 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f   May you find fo
1580: 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f  rgiveness for yo
1590: 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69  urself and forgi
15a0: 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20  ve others..**   
15b0: 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65 20 66   May you share f
15c0: 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b  reely, never tak
15d0: 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f  ing more than yo
15e0: 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a  u give..**.*****
15f0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1600: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1610: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1620: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1630: 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20  *********.**.** 
1640: 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 61 69  This file contai
1650: 6e 73 20 63 6f 64 65 20 74 68 61 74 20 69 73 20  ns code that is 
1660: 73 70 65 63 69 66 69 63 20 74 6f 20 57 69 6e 64  specific to Wind
1670: 20 52 69 76 65 72 27 73 20 56 78 57 6f 72 6b 73   River's VxWorks
1680: 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28  .*/.#if defined(
1690: 5f 5f 52 54 50 5f 5f 29 20 7c 7c 20 64 65 66 69  __RTP__) || defi
16a0: 6e 65 64 28 5f 57 52 53 5f 4b 45 52 4e 45 4c 29  ned(_WRS_KERNEL)
16b0: 0a 2f 2a 20 54 68 69 73 20 69 73 20 56 78 57 6f  ./* This is VxWo
16c0: 72 6b 73 2e 20 20 53 65 74 20 75 70 20 74 68 69  rks.  Set up thi
16d0: 6e 67 73 20 73 70 65 63 69 61 6c 6c 79 20 66 6f  ngs specially fo
16e0: 72 20 74 68 61 74 20 4f 53 0a 2a 2f 0a 23 69 6e  r that OS.*/.#in
16f0: 63 6c 75 64 65 20 3c 76 78 57 6f 72 6b 73 2e 68  clude <vxWorks.h
1700: 3e 0a 23 69 6e 63 6c 75 64 65 20 3c 70 74 68 72  >.#include <pthr
1710: 65 61 64 2e 68 3e 20 20 2f 2a 20 61 6d 61 6c 67  ead.h>  /* amalg
1720: 61 6d 61 74 6f 72 3a 20 64 6f 6e 74 63 61 63 68  amator: dontcach
1730: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 4f 53 5f  e */.#define OS_
1740: 56 58 57 4f 52 4b 53 20 31 0a 23 64 65 66 69 6e  VXWORKS 1.#defin
1750: 65 20 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45  e SQLITE_OS_OTHE
1760: 52 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  R 0.#define SQLI
1770: 54 45 5f 48 4f 4d 45 47 52 4f 57 4e 5f 52 45 43  TE_HOMEGROWN_REC
1780: 55 52 53 49 56 45 5f 4d 55 54 45 58 20 31 0a 23  URSIVE_MUTEX 1.#
1790: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4d  define SQLITE_OM
17a0: 49 54 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f  IT_LOAD_EXTENSIO
17b0: 4e 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  N 1.#define SQLI
17c0: 54 45 5f 45 4e 41 42 4c 45 5f 4c 4f 43 4b 49 4e  TE_ENABLE_LOCKIN
17d0: 47 5f 53 54 59 4c 45 20 30 0a 23 64 65 66 69 6e  G_STYLE 0.#defin
17e0: 65 20 48 41 56 45 5f 55 54 49 4d 45 20 31 0a 23  e HAVE_UTIME 1.#
17f0: 65 6c 73 65 0a 2f 2a 20 54 68 69 73 20 69 73 20  else./* This is 
1800: 6e 6f 74 20 56 78 57 6f 72 6b 73 2e 20 2a 2f 0a  not VxWorks. */.
1810: 23 64 65 66 69 6e 65 20 4f 53 5f 56 58 57 4f 52  #define OS_VXWOR
1820: 4b 53 20 30 0a 23 64 65 66 69 6e 65 20 48 41 56  KS 0.#define HAV
1830: 45 5f 46 43 48 4f 57 4e 20 31 0a 23 64 65 66 69  E_FCHOWN 1.#defi
1840: 6e 65 20 48 41 56 45 5f 52 45 41 44 4c 49 4e 4b  ne HAVE_READLINK
1850: 20 31 0a 23 64 65 66 69 6e 65 20 48 41 56 45 5f   1.#define HAVE_
1860: 4c 53 54 41 54 20 31 0a 23 65 6e 64 69 66 20 2f  LSTAT 1.#endif /
1870: 2a 20 64 65 66 69 6e 65 64 28 5f 57 52 53 5f 4b  * defined(_WRS_K
1880: 45 52 4e 45 4c 29 20 2a 2f 0a 0a 2f 2a 2a 2a 2a  ERNEL) */../****
1890: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 45 6e 64 20 6f  ********** End o
18a0: 66 20 76 78 77 6f 72 6b 73 2e 68 20 2a 2a 2a 2a  f vxworks.h ****
18b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
18c0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
18d0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a  *********/./****
18e0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 43 6f 6e 74 69  ********** Conti
18f0: 6e 75 69 6e 67 20 77 68 65 72 65 20 77 65 20 6c  nuing where we l
1900: 65 66 74 20 6f 66 66 20 69 6e 20 73 71 6c 69 74  eft off in sqlit
1910: 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  eInt.h *********
1920: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 0a 2f 2a 0a 2a  *********/../*.*
1930: 2a 20 54 68 65 73 65 20 23 64 65 66 69 6e 65 73  * These #defines
1940: 20 73 68 6f 75 6c 64 20 65 6e 61 62 6c 65 20 3e   should enable >
1950: 32 47 42 20 66 69 6c 65 20 73 75 70 70 6f 72 74  2GB file support
1960: 20 6f 6e 20 50 4f 53 49 58 20 69 66 20 74 68 65   on POSIX if the
1970: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f  .** underlying o
1980: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
1990: 73 75 70 70 6f 72 74 73 20 69 74 2e 20 20 49 66  supports it.  If
19a0: 20 74 68 65 20 4f 53 20 6c 61 63 6b 73 0a 2a 2a   the OS lacks.**
19b0: 20 6c 61 72 67 65 20 66 69 6c 65 20 73 75 70 70   large file supp
19c0: 6f 72 74 2c 20 6f 72 20 69 66 20 74 68 65 20 4f  ort, or if the O
19d0: 53 20 69 73 20 77 69 6e 64 6f 77 73 2c 20 74 68  S is windows, th
19e0: 65 73 65 20 73 68 6f 75 6c 64 20 62 65 20 6e 6f  ese should be no
19f0: 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 54 69 63 6b  -ops..**.** Tick
1a00: 65 74 20 23 32 37 33 39 3a 20 20 54 68 65 20 5f  et #2739:  The _
1a10: 4c 41 52 47 45 46 49 4c 45 5f 53 4f 55 52 43 45  LARGEFILE_SOURCE
1a20: 20 6d 61 63 72 6f 20 6d 75 73 74 20 61 70 70 65   macro must appe
1a30: 61 72 20 62 65 66 6f 72 65 20 61 6e 79 0a 2a 2a  ar before any.**
1a40: 20 73 79 73 74 65 6d 20 23 69 6e 63 6c 75 64 65   system #include
1a50: 73 2e 20 20 48 65 6e 63 65 2c 20 74 68 69 73 20  s.  Hence, this 
1a60: 62 6c 6f 63 6b 20 6f 66 20 63 6f 64 65 20 6d 75  block of code mu
1a70: 73 74 20 62 65 20 74 68 65 20 76 65 72 79 20 66  st be the very f
1a80: 69 72 73 74 0a 2a 2a 20 63 6f 64 65 20 69 6e 20  irst.** code in 
1a90: 61 6c 6c 20 73 6f 75 72 63 65 20 66 69 6c 65 73  all source files
1aa0: 2e 0a 2a 2a 0a 2a 2a 20 4c 61 72 67 65 20 66 69  ..**.** Large fi
1ab0: 6c 65 20 73 75 70 70 6f 72 74 20 63 61 6e 20 62  le support can b
1ac0: 65 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67  e disabled using
1ad0: 20 74 68 65 20 2d 44 53 51 4c 49 54 45 5f 44 49   the -DSQLITE_DI
1ae0: 53 41 42 4c 45 5f 4c 46 53 20 73 77 69 74 63 68  SABLE_LFS switch
1af0: 0a 2a 2a 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  .** on the compi
1b00: 6c 65 72 20 63 6f 6d 6d 61 6e 64 20 6c 69 6e 65  ler command line
1b10: 2e 20 20 54 68 69 73 20 69 73 20 6e 65 63 65 73  .  This is neces
1b20: 73 61 72 79 20 69 66 20 79 6f 75 20 61 72 65 20  sary if you are 
1b30: 63 6f 6d 70 69 6c 69 6e 67 0a 2a 2a 20 6f 6e 20  compiling.** on 
1b40: 61 20 72 65 63 65 6e 74 20 6d 61 63 68 69 6e 65  a recent machine
1b50: 20 28 65 78 3a 20 52 65 64 20 48 61 74 20 37 2e   (ex: Red Hat 7.
1b60: 32 29 20 62 75 74 20 79 6f 75 20 77 61 6e 74 20  2) but you want 
1b70: 79 6f 75 72 20 63 6f 64 65 20 74 6f 20 77 6f 72  your code to wor
1b80: 6b 0a 2a 2a 20 6f 6e 20 61 6e 20 6f 6c 64 65 72  k.** on an older
1b90: 20 6d 61 63 68 69 6e 65 20 28 65 78 3a 20 52 65   machine (ex: Re
1ba0: 64 20 48 61 74 20 36 2e 30 29 2e 20 20 49 66 20  d Hat 6.0).  If 
1bb0: 79 6f 75 20 63 6f 6d 70 69 6c 65 20 6f 6e 20 52  you compile on R
1bc0: 65 64 20 48 61 74 20 37 2e 32 0a 2a 2a 20 77 69  ed Hat 7.2.** wi
1bd0: 74 68 6f 75 74 20 74 68 69 73 20 6f 70 74 69 6f  thout this optio
1be0: 6e 2c 20 4c 46 53 20 69 73 20 65 6e 61 62 6c 65  n, LFS is enable
1bf0: 2e 20 20 42 75 74 20 4c 46 53 20 64 6f 65 73 20  .  But LFS does 
1c00: 6e 6f 74 20 65 78 69 73 74 20 69 6e 20 74 68 65  not exist in the
1c10: 20 6b 65 72 6e 65 6c 0a 2a 2a 20 69 6e 20 52 65   kernel.** in Re
1c20: 64 20 48 61 74 20 36 2e 30 2c 20 73 6f 20 74 68  d Hat 6.0, so th
1c30: 65 20 63 6f 64 65 20 77 6f 6e 27 74 20 77 6f 72  e code won't wor
1c40: 6b 2e 20 20 48 65 6e 63 65 2c 20 66 6f 72 20 6d  k.  Hence, for m
1c50: 61 78 69 6d 75 6d 20 62 69 6e 61 72 79 0a 2a 2a  aximum binary.**
1c60: 20 70 6f 72 74 61 62 69 6c 69 74 79 20 79 6f 75   portability you
1c70: 20 73 68 6f 75 6c 64 20 6f 6d 69 74 20 4c 46 53   should omit LFS
1c80: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 76  ..**.** The prev
1c90: 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 20 77  ious paragraph w
1ca0: 61 73 20 77 72 69 74 74 65 6e 20 69 6e 20 32 30  as written in 20
1cb0: 30 35 2e 20 20 28 54 68 69 73 20 70 61 72 61 67  05.  (This parag
1cc0: 72 61 70 68 20 69 73 20 77 72 69 74 74 65 6e 0a  raph is written.
1cd0: 2a 2a 20 6f 6e 20 32 30 30 38 2d 31 31 2d 32 38  ** on 2008-11-28
1ce0: 2e 29 20 54 68 65 73 65 20 64 61 79 73 2c 20 61  .) These days, a
1cf0: 6c 6c 20 4c 69 6e 75 78 20 6b 65 72 6e 65 6c 73  ll Linux kernels
1d00: 20 73 75 70 70 6f 72 74 20 6c 61 72 67 65 20 66   support large f
1d10: 69 6c 65 73 2c 20 73 6f 0a 2a 2a 20 79 6f 75 20  iles, so.** you 
1d20: 73 68 6f 75 6c 64 20 70 72 6f 62 61 62 6c 79 20  should probably 
1d30: 6c 65 61 76 65 20 4c 46 53 20 65 6e 61 62 6c 65  leave LFS enable
1d40: 64 2e 20 20 42 75 74 20 73 6f 6d 65 20 65 6d 62  d.  But some emb
1d50: 65 64 64 65 64 20 70 6c 61 74 66 6f 72 6d 73 20  edded platforms 
1d60: 6d 69 67 68 74 0a 2a 2a 20 6c 61 63 6b 20 4c 46  might.** lack LF
1d70: 53 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  S in which case 
1d80: 74 68 65 20 53 51 4c 49 54 45 5f 44 49 53 41 42  the SQLITE_DISAB
1d90: 4c 45 5f 4c 46 53 20 6d 61 63 72 6f 20 6d 69 67  LE_LFS macro mig
1da0: 68 74 20 73 74 69 6c 6c 20 62 65 20 75 73 65 66  ht still be usef
1db0: 75 6c 2e 0a 2a 2a 0a 2a 2a 20 53 69 6d 69 6c 61  ul..**.** Simila
1dc0: 72 20 69 73 20 74 72 75 65 20 66 6f 72 20 4d 61  r is true for Ma
1dd0: 63 20 4f 53 20 58 2e 20 20 4c 46 53 20 69 73 20  c OS X.  LFS is 
1de0: 6f 6e 6c 79 20 73 75 70 70 6f 72 74 65 64 20 6f  only supported o
1df0: 6e 20 4d 61 63 20 4f 53 20 58 20 39 20 61 6e 64  n Mac OS X 9 and
1e00: 20 6c 61 74 65 72 2e 0a 2a 2f 0a 23 69 66 6e 64   later..*/.#ifnd
1e10: 65 66 20 53 51 4c 49 54 45 5f 44 49 53 41 42 4c  ef SQLITE_DISABL
1e20: 45 5f 4c 46 53 0a 23 20 64 65 66 69 6e 65 20 5f  E_LFS.# define _
1e30: 4c 41 52 47 45 5f 46 49 4c 45 20 20 20 20 20 20  LARGE_FILE      
1e40: 20 31 0a 23 20 69 66 6e 64 65 66 20 5f 46 49 4c   1.# ifndef _FIL
1e50: 45 5f 4f 46 46 53 45 54 5f 42 49 54 53 0a 23 20  E_OFFSET_BITS.# 
1e60: 20 20 64 65 66 69 6e 65 20 5f 46 49 4c 45 5f 4f    define _FILE_O
1e70: 46 46 53 45 54 5f 42 49 54 53 20 36 34 0a 23 20  FFSET_BITS 64.# 
1e80: 65 6e 64 69 66 0a 23 20 64 65 66 69 6e 65 20 5f  endif.# define _
1e90: 4c 41 52 47 45 46 49 4c 45 5f 53 4f 55 52 43 45  LARGEFILE_SOURCE
1ea0: 20 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a 20 57 68   1.#endif../* Wh
1eb0: 61 74 20 76 65 72 73 69 6f 6e 20 6f 66 20 47 43  at version of GC
1ec0: 43 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 2e  C is being used.
1ed0: 20 20 30 20 6d 65 61 6e 73 20 47 43 43 20 69 73    0 means GCC is
1ee0: 20 6e 6f 74 20 62 65 69 6e 67 20 75 73 65 64 20   not being used 
1ef0: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 47 4e 55 43  */.#ifdef __GNUC
1f00: 5f 5f 0a 23 20 64 65 66 69 6e 65 20 47 43 43 5f  __.# define GCC_
1f10: 56 45 52 53 49 4f 4e 20 28 5f 5f 47 4e 55 43 5f  VERSION (__GNUC_
1f20: 5f 2a 31 30 30 30 30 30 30 2b 5f 5f 47 4e 55 43  _*1000000+__GNUC
1f30: 5f 4d 49 4e 4f 52 5f 5f 2a 31 30 30 30 2b 5f 5f  _MINOR__*1000+__
1f40: 47 4e 55 43 5f 50 41 54 43 48 4c 45 56 45 4c 5f  GNUC_PATCHLEVEL_
1f50: 5f 29 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e  _).#else.# defin
1f60: 65 20 47 43 43 5f 56 45 52 53 49 4f 4e 20 30 0a  e GCC_VERSION 0.
1f70: 23 65 6e 64 69 66 0a 0a 2f 2a 20 4e 65 65 64 65  #endif../* Neede
1f80: 64 20 66 6f 72 20 76 61 72 69 6f 75 73 20 64 65  d for various de
1f90: 66 69 6e 69 74 69 6f 6e 73 2e 2e 2e 20 2a 2f 0a  finitions... */.
1fa0: 23 69 66 20 64 65 66 69 6e 65 64 28 5f 5f 47 4e  #if defined(__GN
1fb0: 55 43 5f 5f 29 20 26 26 20 21 64 65 66 69 6e 65  UC__) && !define
1fc0: 64 28 5f 47 4e 55 5f 53 4f 55 52 43 45 29 0a 23  d(_GNU_SOURCE).#
1fd0: 20 64 65 66 69 6e 65 20 5f 47 4e 55 5f 53 4f 55   define _GNU_SOU
1fe0: 52 43 45 0a 23 65 6e 64 69 66 0a 0a 23 69 66 20  RCE.#endif..#if 
1ff0: 64 65 66 69 6e 65 64 28 5f 5f 4f 70 65 6e 42 53  defined(__OpenBS
2000: 44 5f 5f 29 20 26 26 20 21 64 65 66 69 6e 65 64  D__) && !defined
2010: 28 5f 42 53 44 5f 53 4f 55 52 43 45 29 0a 23 20  (_BSD_SOURCE).# 
2020: 64 65 66 69 6e 65 20 5f 42 53 44 5f 53 4f 55 52  define _BSD_SOUR
2030: 43 45 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  CE.#endif../*.**
2040: 20 46 6f 72 20 4d 69 6e 47 57 2c 20 63 68 65 63   For MinGW, chec
2050: 6b 20 74 6f 20 73 65 65 20 69 66 20 77 65 20 63  k to see if we c
2060: 61 6e 20 69 6e 63 6c 75 64 65 20 74 68 65 20 68  an include the h
2070: 65 61 64 65 72 20 66 69 6c 65 20 63 6f 6e 74 61  eader file conta
2080: 69 6e 69 6e 67 20 69 74 73 0a 2a 2a 20 76 65 72  ining its.** ver
2090: 73 69 6f 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  sion information
20a0: 2c 20 61 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68  , among other th
20b0: 69 6e 67 73 2e 20 20 4e 6f 72 6d 61 6c 6c 79 2c  ings.  Normally,
20c0: 20 74 68 69 73 20 69 6e 74 65 72 6e 61 6c 20 4d   this internal M
20d0: 69 6e 47 57 0a 2a 2a 20 68 65 61 64 65 72 20 66  inGW.** header f
20e0: 69 6c 65 20 77 6f 75 6c 64 20 5b 6f 6e 6c 79 5d  ile would [only]
20f0: 20 62 65 20 69 6e 63 6c 75 64 65 64 20 61 75 74   be included aut
2100: 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 6f 74  omatically by ot
2110: 68 65 72 20 4d 69 6e 47 57 20 68 65 61 64 65 72  her MinGW header
2120: 0a 2a 2a 20 66 69 6c 65 73 3b 20 68 6f 77 65 76  .** files; howev
2130: 65 72 2c 20 74 68 65 20 63 6f 6e 74 61 69 6e 65  er, the containe
2140: 64 20 76 65 72 73 69 6f 6e 20 69 6e 66 6f 72 6d  d version inform
2150: 61 74 69 6f 6e 20 69 73 20 6e 6f 77 20 72 65 71  ation is now req
2160: 75 69 72 65 64 20 62 79 20 74 68 69 73 0a 2a 2a  uired by this.**
2170: 20 68 65 61 64 65 72 20 66 69 6c 65 20 74 6f 20   header file to 
2180: 77 6f 72 6b 20 61 72 6f 75 6e 64 20 62 69 6e 61  work around bina
2190: 72 79 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ry compatibility
21a0: 20 69 73 73 75 65 73 20 28 73 65 65 20 62 65 6c   issues (see bel
21b0: 6f 77 29 20 61 6e 64 0a 2a 2a 20 74 68 69 73 20  ow) and.** this 
21c0: 69 73 20 74 68 65 20 6f 6e 6c 79 20 6b 6e 6f 77  is the only know
21d0: 6e 20 77 61 79 20 74 6f 20 72 65 6c 69 61 62 6c  n way to reliabl
21e0: 79 20 6f 62 74 61 69 6e 20 69 74 2e 20 20 54 68  y obtain it.  Th
21f0: 69 73 20 65 6e 74 69 72 65 20 23 69 66 20 62 6c  is entire #if bl
2200: 6f 63 6b 0a 2a 2a 20 77 6f 75 6c 64 20 62 65 20  ock.** would be 
2210: 63 6f 6d 70 6c 65 74 65 6c 79 20 75 6e 6e 65 63  completely unnec
2220: 65 73 73 61 72 79 20 69 66 20 74 68 65 72 65 20  essary if there 
2230: 77 61 73 20 61 6e 79 20 6f 74 68 65 72 20 77 61  was any other wa
2240: 79 20 6f 66 20 64 65 74 65 63 74 69 6e 67 0a 2a  y of detecting.*
2250: 2a 20 4d 69 6e 47 57 20 76 69 61 20 74 68 65 69  * MinGW via thei
2260: 72 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 28  r preprocessor (
2270: 65 2e 67 2e 20 69 66 20 74 68 65 79 20 63 75 73  e.g. if they cus
2280: 74 6f 6d 69 7a 65 64 20 74 68 65 69 72 20 47 43  tomized their GC
2290: 43 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 73  C to define.** s
22a0: 6f 6d 65 20 4d 69 6e 47 57 2d 73 70 65 63 69 66  ome MinGW-specif
22b0: 69 63 20 6d 61 63 72 6f 73 29 2e 20 20 57 68 65  ic macros).  Whe
22c0: 6e 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20  n compiling for 
22d0: 4d 69 6e 47 57 2c 20 65 69 74 68 65 72 20 74 68  MinGW, either th
22e0: 65 0a 2a 2a 20 5f 48 41 56 45 5f 4d 49 4e 47 57  e.** _HAVE_MINGW
22f0: 5f 48 20 6f 72 20 5f 48 41 56 45 5f 5f 4d 49 4e  _H or _HAVE__MIN
2300: 47 57 5f 48 20 28 6e 6f 74 65 20 74 68 65 20 65  GW_H (note the e
2310: 78 74 72 61 20 75 6e 64 65 72 73 63 6f 72 65 29  xtra underscore)
2320: 20 6d 61 63 72 6f 20 6d 75 73 74 20 62 65 0a 2a   macro must be.*
2330: 2a 20 64 65 66 69 6e 65 64 3b 20 6f 74 68 65 72  * defined; other
2340: 77 69 73 65 2c 20 64 65 74 65 63 74 69 6f 6e 20  wise, detection 
2350: 6f 66 20 63 6f 6e 64 69 74 69 6f 6e 73 20 73 70  of conditions sp
2360: 65 63 69 66 69 63 20 74 6f 20 4d 69 6e 47 57 20  ecific to MinGW 
2370: 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 69 73 61 62  will be.** disab
2380: 6c 65 64 2e 0a 2a 2f 0a 23 69 66 20 64 65 66 69  led..*/.#if defi
2390: 6e 65 64 28 5f 48 41 56 45 5f 4d 49 4e 47 57 5f  ned(_HAVE_MINGW_
23a0: 48 29 0a 23 20 69 6e 63 6c 75 64 65 20 22 6d 69  H).# include "mi
23b0: 6e 67 77 2e 68 22 0a 23 65 6c 69 66 20 64 65 66  ngw.h".#elif def
23c0: 69 6e 65 64 28 5f 48 41 56 45 5f 5f 4d 49 4e 47  ined(_HAVE__MING
23d0: 57 5f 48 29 0a 23 20 69 6e 63 6c 75 64 65 20 22  W_H).# include "
23e0: 5f 6d 69 6e 67 77 2e 68 22 0a 23 65 6e 64 69 66  _mingw.h".#endif
23f0: 0a 0a 2f 2a 0a 2a 2a 20 46 6f 72 20 4d 69 6e 47  ../*.** For MinG
2400: 57 20 76 65 72 73 69 6f 6e 20 34 2e 78 20 28 61  W version 4.x (a
2410: 6e 64 20 68 69 67 68 65 72 29 2c 20 63 68 65 63  nd higher), chec
2420: 6b 20 74 6f 20 73 65 65 20 69 66 20 74 68 65 20  k to see if the 
2430: 5f 55 53 45 5f 33 32 42 49 54 5f 54 49 4d 45 5f  _USE_32BIT_TIME_
2440: 54 0a 2a 2a 20 64 65 66 69 6e 65 20 69 73 20 72  T.** define is r
2450: 65 71 75 69 72 65 64 20 74 6f 20 6d 61 69 6e 74  equired to maint
2460: 61 69 6e 20 62 69 6e 61 72 79 20 63 6f 6d 70 61  ain binary compa
2470: 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 74 68  tibility with th
2480: 65 20 4d 53 56 43 20 72 75 6e 74 69 6d 65 0a 2a  e MSVC runtime.*
2490: 2a 20 6c 69 62 72 61 72 79 20 69 6e 20 75 73 65  * library in use
24a0: 20 28 65 2e 67 2e 20 66 6f 72 20 57 69 6e 64 6f   (e.g. for Windo
24b0: 77 73 20 58 50 29 2e 0a 2a 2f 0a 23 69 66 20 21  ws XP)..*/.#if !
24c0: 64 65 66 69 6e 65 64 28 5f 55 53 45 5f 33 32 42  defined(_USE_32B
24d0: 49 54 5f 54 49 4d 45 5f 54 29 20 26 26 20 21 64  IT_TIME_T) && !d
24e0: 65 66 69 6e 65 64 28 5f 55 53 45 5f 36 34 42 49  efined(_USE_64BI
24f0: 54 5f 54 49 4d 45 5f 54 29 20 26 26 20 5c 0a 20  T_TIME_T) && \. 
2500: 20 20 20 64 65 66 69 6e 65 64 28 5f 57 49 4e 33     defined(_WIN3
2510: 32 29 20 26 26 20 21 64 65 66 69 6e 65 64 28 5f  2) && !defined(_
2520: 57 49 4e 36 34 29 20 26 26 20 5c 0a 20 20 20 20  WIN64) && \.    
2530: 64 65 66 69 6e 65 64 28 5f 5f 4d 49 4e 47 57 5f  defined(__MINGW_
2540: 4d 41 4a 4f 52 5f 56 45 52 53 49 4f 4e 29 20 26  MAJOR_VERSION) &
2550: 26 20 5f 5f 4d 49 4e 47 57 5f 4d 41 4a 4f 52 5f  & __MINGW_MAJOR_
2560: 56 45 52 53 49 4f 4e 20 3e 3d 20 34 20 26 26 20  VERSION >= 4 && 
2570: 5c 0a 20 20 20 20 64 65 66 69 6e 65 64 28 5f 5f  \.    defined(__
2580: 4d 53 56 43 52 54 5f 5f 29 0a 23 20 64 65 66 69  MSVCRT__).# defi
2590: 6e 65 20 5f 55 53 45 5f 33 32 42 49 54 5f 54 49  ne _USE_32BIT_TI
25a0: 4d 45 5f 54 0a 23 65 6e 64 69 66 0a 0a 2f 2a 20  ME_T.#endif../* 
25b0: 54 68 65 20 70 75 62 6c 69 63 20 53 51 4c 69 74  The public SQLit
25c0: 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68  e interface.  Th
25d0: 65 20 5f 46 49 4c 45 5f 4f 46 46 53 45 54 5f 42  e _FILE_OFFSET_B
25e0: 49 54 53 20 6d 61 63 72 6f 20 6d 75 73 74 20 61  ITS macro must a
25f0: 70 70 65 61 72 0a 2a 2a 20 66 69 72 73 74 20 69  ppear.** first i
2600: 6e 20 51 4e 58 2e 20 20 41 6c 73 6f 2c 20 74 68  n QNX.  Also, th
2610: 65 20 5f 55 53 45 5f 33 32 42 49 54 5f 54 49 4d  e _USE_32BIT_TIM
2620: 45 5f 54 20 6d 61 63 72 6f 20 6d 75 73 74 20 61  E_T macro must a
2630: 70 70 65 61 72 20 66 69 72 73 74 20 66 6f 72 0a  ppear first for.
2640: 2a 2a 20 4d 69 6e 47 57 2e 0a 2a 2f 0a 2f 2a 2a  ** MinGW..*/./**
2650: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 49 6e 63  ************ Inc
2660: 6c 75 64 65 20 73 71 6c 69 74 65 33 2e 68 20 69  lude sqlite3.h i
2670: 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20  n the middle of 
2680: 73 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a  sqliteInt.h ****
2690: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a  ***********/./**
26a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67  ************ Beg
26b0: 69 6e 20 66 69 6c 65 20 73 71 6c 69 74 65 33 2e  in file sqlite3.
26c0: 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  h **************
26d0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
26e0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a  ***********/./*.
26f0: 2a 2a 20 32 30 30 31 20 53 65 70 74 65 6d 62 65  ** 2001 Septembe
2700: 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  r 15.**.** The a
2710: 75 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20  uthor disclaims 
2720: 63 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69  copyright to thi
2730: 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20  s source code.  
2740: 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61  In place of.** a
2750: 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68   legal notice, h
2760: 65 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e  ere is a blessin
2770: 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20  g:.**.**    May 
2780: 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20  you do good and 
2790: 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20  not evil..**    
27a0: 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72  May you find for
27b0: 67 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75  giveness for you
27c0: 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76  rself and forgiv
27d0: 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20  e others..**    
27e0: 4d 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72  May you share fr
27f0: 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69  eely, never taki
2800: 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75  ng more than you
2810: 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a   give..**.******
2820: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2830: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2840: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2850: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2860: 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68 65 61 64  ***.** This head
2870: 65 72 20 66 69 6c 65 20 64 65 66 69 6e 65 73 20  er file defines 
2880: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 68  the interface th
2890: 61 74 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  at the SQLite li
28a0: 62 72 61 72 79 0a 2a 2a 20 70 72 65 73 65 6e 74  brary.** present
28b0: 73 20 74 6f 20 63 6c 69 65 6e 74 20 70 72 6f 67  s to client prog
28c0: 72 61 6d 73 2e 20 20 49 66 20 61 20 43 2d 66 75  rams.  If a C-fu
28d0: 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63 74 75 72  nction, structur
28e0: 65 2c 20 64 61 74 61 74 79 70 65 2c 0a 2a 2a 20  e, datatype,.** 
28f0: 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69  or constant defi
2900: 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20  nition does not 
2910: 61 70 70 65 61 72 20 69 6e 20 74 68 69 73 20 66  appear in this f
2920: 69 6c 65 2c 20 74 68 65 6e 20 69 74 20 69 73 0a  ile, then it is.
2930: 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c 69 73 68  ** not a publish
2940: 65 64 20 41 50 49 20 6f 66 20 53 51 4c 69 74 65  ed API of SQLite
2950: 2c 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20  , is subject to 
2960: 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74 0a 2a  change without.*
2970: 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64 20 73 68  * notice, and sh
2980: 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72 65 66 65  ould not be refe
2990: 72 65 6e 63 65 64 20 62 79 20 70 72 6f 67 72 61  renced by progra
29a0: 6d 73 20 74 68 61 74 20 75 73 65 20 53 51 4c 69  ms that use SQLi
29b0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f  te..**.** Some o
29c0: 66 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e  f the definition
29d0: 73 20 74 68 61 74 20 61 72 65 20 69 6e 20 74 68  s that are in th
29e0: 69 73 20 66 69 6c 65 20 61 72 65 20 6d 61 72 6b  is file are mark
29f0: 65 64 20 61 73 0a 2a 2a 20 22 65 78 70 65 72 69  ed as.** "experi
2a00: 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70 65 72 69  mental".  Experi
2a10: 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65  mental interface
2a20: 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e  s are normally n
2a30: 65 77 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 72  ew.** features r
2a40: 65 63 65 6e 74 6c 79 20 61 64 64 65 64 20 74 6f  ecently added to
2a50: 20 53 51 4c 69 74 65 2e 20 20 57 65 20 64 6f 20   SQLite.  We do 
2a60: 6e 6f 74 20 61 6e 74 69 63 69 70 61 74 65 20 63  not anticipate c
2a70: 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 65 78 70  hanges.** to exp
2a80: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
2a90: 61 63 65 73 20 62 75 74 20 72 65 73 65 72 76 65  aces but reserve
2aa0: 20 74 68 65 20 72 69 67 68 74 20 74 6f 20 6d 61   the right to ma
2ab0: 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73  ke minor changes
2ac0: 0a 2a 2a 20 69 66 20 65 78 70 65 72 69 65 6e 63  .** if experienc
2ad0: 65 20 66 72 6f 6d 20 75 73 65 20 22 69 6e 20 74  e from use "in t
2ae0: 68 65 20 77 69 6c 64 22 20 73 75 67 67 65 73 74  he wild" suggest
2af0: 20 73 75 63 68 20 63 68 61 6e 67 65 73 20 61 72   such changes ar
2b00: 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a  e prudent..**.**
2b10: 20 54 68 65 20 6f 66 66 69 63 69 61 6c 20 43 2d   The official C-
2b20: 6c 61 6e 67 75 61 67 65 20 41 50 49 20 64 6f 63  language API doc
2b30: 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 53  umentation for S
2b40: 51 4c 69 74 65 20 69 73 20 64 65 72 69 76 65 64  QLite is derived
2b50: 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74  .** from comment
2b60: 73 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2e 20  s in this file. 
2b70: 20 54 68 69 73 20 66 69 6c 65 20 69 73 20 74 68   This file is th
2b80: 65 20 61 75 74 68 6f 72 69 74 61 74 69 76 65 20  e authoritative 
2b90: 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77  source.** on how
2ba0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
2bb0: 65 73 20 61 72 65 20 73 75 70 70 6f 73 65 64 20  es are supposed 
2bc0: 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a  to operate..**.*
2bd0: 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  * The name of th
2be0: 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20 63 6f  is file under co
2bf0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
2c00: 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c 69 74  gement is "sqlit
2c10: 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68 65 20  e.h.in"..** The 
2c20: 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73 20 73  makefile makes s
2c30: 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e 67 65  ome minor change
2c40: 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65 20 28  s to this file (
2c50: 73 75 63 68 20 61 73 20 69 6e 73 65 72 74 69 6e  such as insertin
2c60: 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69 6f 6e  g.** the version
2c70: 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63 68 61   number) and cha
2c80: 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20 74 6f  nges its name to
2c90: 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61 73 0a   "sqlite3.h" as.
2ca0: 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65 20 62  ** part of the b
2cb0: 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a 2a 2f  uild process..*/
2cc0: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 33  .#ifndef SQLITE3
2cd0: 5f 48 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  _H.#define SQLIT
2ce0: 45 33 5f 48 0a 23 69 6e 63 6c 75 64 65 20 3c 73  E3_H.#include <s
2cf0: 74 64 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20  tdarg.h>     /* 
2d00: 4e 65 65 64 65 64 20 66 6f 72 20 74 68 65 20 64  Needed for the d
2d10: 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f  efinition of va_
2d20: 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d  list */../*.** M
2d30: 61 6b 65 20 73 75 72 65 20 77 65 20 63 61 6e 20  ake sure we can 
2d40: 63 61 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20  call this stuff 
2d50: 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66  from C++..*/.#if
2d60: 20 30 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a   0.extern "C" {.
2d70: 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 50  #endif.../*.** P
2d80: 72 6f 76 69 64 65 20 74 68 65 20 61 62 69 6c 69  rovide the abili
2d90: 74 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 6c  ty to override l
2da0: 69 6e 6b 61 67 65 20 66 65 61 74 75 72 65 73 20  inkage features 
2db0: 6f 66 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  of the interface
2dc0: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
2dd0: 49 54 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66  ITE_EXTERN.# def
2de0: 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52  ine SQLITE_EXTER
2df0: 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a  N extern.#endif.
2e00: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41  #ifndef SQLITE_A
2e10: 50 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  PI.# define SQLI
2e20: 54 45 5f 41 50 49 0a 23 65 6e 64 69 66 0a 23 69  TE_API.#endif.#i
2e30: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 43 44 45  fndef SQLITE_CDE
2e40: 43 4c 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  CL.# define SQLI
2e50: 54 45 5f 43 44 45 43 4c 0a 23 65 6e 64 69 66 0a  TE_CDECL.#endif.
2e60: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41  #ifndef SQLITE_A
2e70: 50 49 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20  PICALL.# define 
2e80: 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23  SQLITE_APICALL.#
2e90: 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51  endif.#ifndef SQ
2ea0: 4c 49 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64  LITE_STDCALL.# d
2eb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44  efine SQLITE_STD
2ec0: 43 41 4c 4c 20 53 51 4c 49 54 45 5f 41 50 49 43  CALL SQLITE_APIC
2ed0: 41 4c 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64  ALL.#endif.#ifnd
2ee0: 65 66 20 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41  ef SQLITE_CALLBA
2ef0: 43 4b 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  CK.# define SQLI
2f00: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 65 6e 64  TE_CALLBACK.#end
2f10: 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  if.#ifndef SQLIT
2f20: 45 5f 53 59 53 41 50 49 0a 23 20 64 65 66 69 6e  E_SYSAPI.# defin
2f30: 65 20 53 51 4c 49 54 45 5f 53 59 53 41 50 49 0a  e SQLITE_SYSAPI.
2f40: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68  #endif../*.** Th
2f50: 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73  ese no-op macros
2f60: 20 61 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f   are used in fro
2f70: 6e 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73  nt of interfaces
2f80: 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a   to mark those.*
2f90: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 73 20  * interfaces as 
2fa0: 65 69 74 68 65 72 20 64 65 70 72 65 63 61 74 65  either deprecate
2fb0: 64 20 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61  d or experimenta
2fc0: 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74  l.  New applicat
2fd0: 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  ions.** should n
2fe0: 6f 74 20 75 73 65 20 64 65 70 72 65 63 61 74 65  ot use deprecate
2ff0: 64 20 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74  d interfaces - t
3000: 68 65 79 20 61 72 65 20 73 75 70 70 6f 72 74 65  hey are supporte
3010: 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a  d for backwards.
3020: 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ** compatibility
3030: 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74   only.  Applicat
3040: 69 6f 6e 20 77 72 69 74 65 72 73 20 73 68 6f 75  ion writers shou
3050: 6c 64 20 62 65 20 61 77 61 72 65 20 74 68 61 74  ld be aware that
3060: 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  .** experimental
3070: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
3080: 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
3090: 65 20 69 6e 20 70 6f 69 6e 74 20 72 65 6c 65 61  e in point relea
30a0: 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ses..**.** These
30b0: 20 6d 61 63 72 6f 73 20 75 73 65 64 20 74 6f 20   macros used to 
30c0: 72 65 73 6f 6c 76 65 20 74 6f 20 76 61 72 69 6f  resolve to vario
30d0: 75 73 20 6b 69 6e 64 73 20 6f 66 20 63 6f 6d 70  us kinds of comp
30e0: 69 6c 65 72 20 6d 61 67 69 63 20 74 68 61 74 0a  iler magic that.
30f0: 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65 72 61 74  ** would generat
3100: 65 20 77 61 72 6e 69 6e 67 20 6d 65 73 73 61 67  e warning messag
3110: 65 73 20 77 68 65 6e 20 74 68 65 79 20 77 65 72  es when they wer
3120: 65 20 75 73 65 64 2e 20 20 42 75 74 20 74 68 61  e used.  But tha
3130: 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 6d 61  t.** compiler ma
3140: 67 69 63 20 65 6e 64 65 64 20 75 70 20 67 65 6e  gic ended up gen
3150: 65 72 61 74 69 6e 67 20 73 75 63 68 20 61 20 66  erating such a f
3160: 6c 75 72 72 79 20 6f 66 20 62 75 67 20 72 65 70  lurry of bug rep
3170: 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20 77 65 20  orts.** that we 
3180: 68 61 76 65 20 74 61 6b 65 6e 20 69 74 20 61 6c  have taken it al
3190: 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e 65 20 62  l out and gone b
31a0: 61 63 6b 20 74 6f 20 75 73 69 6e 67 20 73 69 6d  ack to using sim
31b0: 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72  ple.** noop macr
31c0: 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  os..*/.#define S
31d0: 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
31e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
31f0: 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a  EXPERIMENTAL../*
3200: 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65  .** Ensure these
3210: 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f   symbols were no
3220: 74 20 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d  t defined by som
3230: 65 20 70 72 65 76 69 6f 75 73 20 68 65 61 64 65  e previous heade
3240: 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65  r file..*/.#ifde
3250: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
3260: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
3270: 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23  VERSION.#endif.#
3280: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52  ifdef SQLITE_VER
3290: 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e  SION_NUMBER.# un
32a0: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
32b0: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66  ON_NUMBER.#endif
32c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32d0: 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c  : Compile-Time L
32e0: 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e  ibrary Version N
32f0: 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54  umbers.**.** ^(T
3300: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
3310: 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ON] C preprocess
3320: 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74 68 65 20  or macro in the 
3330: 73 71 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72  sqlite3.h header
3340: 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73 20 74 6f  .** evaluates to
3350: 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
3360: 6c 20 74 68 61 74 20 69 73 20 74 68 65 20 53 51  l that is the SQ
3370: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 69 6e 20  Lite version in 
3380: 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 22 58  the.** format "X
3390: 2e 59 2e 5a 22 20 77 68 65 72 65 20 58 20 69 73  .Y.Z" where X is
33a0: 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69   the major versi
33b0: 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c 77 61 79  on number (alway
33c0: 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51 4c 69 74  s 3 for.** SQLit
33d0: 65 33 29 20 61 6e 64 20 59 20 69 73 20 74 68 65  e3) and Y is the
33e0: 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e   minor version n
33f0: 75 6d 62 65 72 20 61 6e 64 20 5a 20 69 73 20 74  umber and Z is t
3400: 68 65 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65  he release numbe
3410: 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 5b 53  r.)^.** ^(The [S
3420: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
3430: 4d 42 45 52 5d 20 43 20 70 72 65 70 72 6f 63 65  MBER] C preproce
3440: 73 73 6f 72 20 6d 61 63 72 6f 20 72 65 73 6f 6c  ssor macro resol
3450: 76 65 73 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ves to an intege
3460: 72 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 61  r.** with the va
3470: 6c 75 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b  lue (X*1000000 +
3480: 20 59 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65   Y*1000 + Z) whe
3490: 72 65 20 58 2c 20 59 2c 20 61 6e 64 20 5a 20 61  re X, Y, and Z a
34a0: 72 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 6e  re the same.** n
34b0: 75 6d 62 65 72 73 20 75 73 65 64 20 69 6e 20 5b  umbers used in [
34c0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2e  SQLITE_VERSION].
34d0: 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )^.** The SQLITE
34e0: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
34f0: 66 6f 72 20 61 6e 79 20 67 69 76 65 6e 20 72 65  for any given re
3500: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
3510: 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20  will also.** be 
3520: 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20  larger than the 
3530: 72 65 6c 65 61 73 65 20 66 72 6f 6d 20 77 68 69  release from whi
3540: 63 68 20 69 74 20 69 73 20 64 65 72 69 76 65 64  ch it is derived
3550: 2e 20 20 45 69 74 68 65 72 20 59 20 77 69 6c 6c  .  Either Y will
3560: 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63 6f 6e 73  .** be held cons
3570: 74 61 6e 74 20 61 6e 64 20 5a 20 77 69 6c 6c 20  tant and Z will 
3580: 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 6f  be incremented o
3590: 72 20 65 6c 73 65 20 59 20 77 69 6c 6c 20 62 65  r else Y will be
35a0: 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a 2a 2a 20   incremented.** 
35b0: 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 72 65  and Z will be re
35c0: 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a  set to zero..**.
35d0: 2a 2a 20 53 69 6e 63 65 20 76 65 72 73 69 6f 6e  ** Since version
35e0: 20 33 2e 36 2e 31 38 2c 20 53 51 4c 69 74 65 20   3.6.18, SQLite 
35f0: 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61 73 20  source code has 
3600: 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e 20 74  been stored in t
3610: 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 68  he.** <a href="h
3620: 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69 6c  ttp://www.fossil
3630: 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73 69  -scm.org/">Fossi
3640: 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  l configuration 
3650: 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73 79  management.** sy
3660: 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65 20  stem</a>.  ^The 
3670: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
3680: 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74 65 73   macro evaluates
3690: 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67 20   to.** a string 
36a0: 77 68 69 63 68 20 69 64 65 6e 74 69 66 69 65 73  which identifies
36b0: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 68   a particular ch
36c0: 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74 65  eck-in of SQLite
36d0: 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73 20 63  .** within its c
36e0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e  onfiguration man
36f0: 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e 20  agement system. 
3700: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55   ^The SQLITE_SOU
3710: 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e 67  RCE_ID.** string
3720: 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61   contains the da
3730: 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66 20 74  te and time of t
3740: 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55 54 43  he check-in (UTC
3750: 29 20 61 6e 64 20 61 6e 20 53 48 41 31 0a 2a 2a  ) and an SHA1.**
3760: 20 68 61 73 68 20 6f 66 20 74 68 65 20 65 6e 74   hash of the ent
3770: 69 72 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e  ire source tree.
3780: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
3790: 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   [sqlite3_libver
37a0: 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  sion()],.** [sql
37b0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
37c0: 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71 6c 69  number()], [sqli
37d0: 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 5d 2c  te3_sourceid()],
37e0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65 72 73  .** [sqlite_vers
37f0: 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
3800: 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e  te_source_id()].
3810: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
3820: 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20 20 20  TE_VERSION      
3830: 20 20 22 33 2e 31 34 2e 30 22 0a 23 64 65 66 69    "3.14.0".#defi
3840: 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  ne SQLITE_VERSIO
3850: 4e 5f 4e 55 4d 42 45 52 20 33 30 31 34 30 30 30  N_NUMBER 3014000
3860: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3870: 53 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22  SOURCE_ID      "
3880: 32 30 31 36 2d 30 38 2d 30 38 20 31 33 3a 34 30  2016-08-08 13:40
3890: 3a 32 37 20 64 35 65 39 38 30 35 37 30 32 38 61  :27 d5e98057028a
38a0: 62 63 66 37 32 31 37 64 30 64 32 62 32 65 32 39  bcf7217d0d2b2e29
38b0: 62 62 62 63 64 66 30 39 64 36 64 65 22 0a 0a 2f  bbbcdf09d6de"../
38c0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
38d0: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
38e0: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
38f0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
3900: 69 74 65 33 5f 76 65 72 73 69 6f 6e 2c 20 73 71  ite3_version, sq
3910: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a  lite3_sourceid.*
3920: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72  *.** These inter
3930: 66 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68  faces provide th
3940: 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
3950: 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54  on as the [SQLIT
3960: 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b  E_VERSION],.** [
3970: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
3980: 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c  UMBER], and [SQL
3990: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43  ITE_SOURCE_ID] C
39a0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
39b0: 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20  cros.** but are 
39c0: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
39d0: 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74  the library inst
39e0: 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65  ead of the heade
39f0: 72 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69  r file.  ^(Cauti
3a00: 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65  ous.** programme
3a10: 72 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65  rs might include
3a20: 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d   assert() statem
3a30: 65 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70  ents in their ap
3a40: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20  plication to.** 
3a50: 76 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75  verify that valu
3a60: 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  es returned by t
3a70: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
3a80: 6d 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73  match the macros
3a90: 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65   in.** the heade
3aa0: 72 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75  r, and thus ensu
3ab0: 72 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c  re that the appl
3ac0: 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f  ication is.** co
3ad0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63  mpiled with matc
3ae0: 68 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64  hing library and
3af0: 20 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a   header files..*
3b00: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
3b10: 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74  ><pre>.** assert
3b20: 28 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  ( sqlite3_libver
3b30: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53  sion_number()==S
3b40: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
3b50: 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72  MBER );.** asser
3b60: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
3b70: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c  3_sourceid(),SQL
3b80: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d 3d  ITE_SOURCE_ID)==
3b90: 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20  0 );.** assert( 
3ba0: 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c  strcmp(sqlite3_l
3bb0: 69 62 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c 49  ibversion(),SQLI
3bc0: 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29  TE_VERSION)==0 )
3bd0: 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
3be0: 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
3bf0: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 65   ^The sqlite3_ve
3c00: 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63  rsion[] string c
3c10: 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73  onstant contains
3c20: 20 74 68 65 20 74 65 78 74 20 6f 66 20 5b 53 51   the text of [SQ
3c30: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a  LITE_VERSION].**
3c40: 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65 20 73 71   macro.  ^The sq
3c50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
3c60: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  () function retu
3c70: 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
3c80: 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20 73   the.** to the s
3c90: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
3ca0: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
3cb0: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  .  The sqlite3_l
3cc0: 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20 66  ibversion().** f
3cd0: 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69  unction is provi
3ce0: 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 44  ded for use in D
3cf0: 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 73  LLs since DLL us
3d00: 65 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e  ers usually do n
3d10: 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69 72 65 63  ot have.** direc
3d20: 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72 69  t access to stri
3d30: 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74  ng constants wit
3d40: 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e 54  hin the DLL.  ^T
3d50: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69  he.** sqlite3_li
3d60: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28  bversion_number(
3d70: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
3d80: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71  ns an integer eq
3d90: 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54  ual to.** [SQLIT
3da0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
3db0: 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
3dc0: 5f 73 6f 75 72 63 65 69 64 28 29 20 66 75 6e 63  _sourceid() func
3dd0: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a 2a  tion returns .**
3de0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
3df0: 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20  string constant 
3e00: 77 68 6f 73 65 20 76 61 6c 75 65 20 69 73 20 74  whose value is t
3e10: 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20 0a  he same as the .
3e20: 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43  ** [SQLITE_SOURC
3e30: 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65  E_ID] C preproce
3e40: 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a  ssor macro..**.*
3e50: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
3e60: 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61  ite_version()] a
3e70: 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63  nd [sqlite_sourc
3e80: 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  e_id()]..*/.SQLI
3e90: 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
3ea0: 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  r sqlite3_versio
3eb0: 6e 5b 5d 20 3d 20 53 51 4c 49 54 45 5f 56 45 52  n[] = SQLITE_VER
3ec0: 53 49 4f 4e 3b 0a 53 51 4c 49 54 45 5f 41 50 49  SION;.SQLITE_API
3ed0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c   const char *SQL
3ee0: 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
3ef0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76  te3_libversion(v
3f00: 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
3f10: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c   const char *SQL
3f20: 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
3f30: 74 65 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69  te3_sourceid(voi
3f40: 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  d);.SQLITE_API i
3f50: 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
3f60: 4c 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  L sqlite3_libver
3f70: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64  sion_number(void
3f80: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
3f90: 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62  EF: Run-Time Lib
3fa0: 72 61 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e  rary Compilation
3fb0: 20 4f 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73   Options Diagnos
3fc0: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tics.**.** ^The 
3fd0: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
3fe0: 70 74 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e  ption_used() fun
3ff0: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20  ction returns 0 
4000: 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74  or 1 .** indicat
4010: 69 6e 67 20 77 68 65 74 68 65 72 20 74 68 65 20  ing whether the 
4020: 73 70 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e  specified option
4030: 20 77 61 73 20 64 65 66 69 6e 65 64 20 61 74 20   was defined at 
4040: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65  .** compile time
4050: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20  .  ^The SQLITE_ 
4060: 70 72 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d  prefix may be om
4070: 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a  itted from the .
4080: 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70  ** option name p
4090: 61 73 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33  assed to sqlite3
40a0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75  _compileoption_u
40b0: 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e  sed().  .**.** ^
40c0: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  The sqlite3_comp
40d0: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20  ileoption_get() 
40e0: 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20  function allows 
40f0: 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65  iterating.** ove
4100: 72 20 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70  r the list of op
4110: 74 69 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20  tions that were 
4120: 64 65 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69  defined at compi
4130: 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65  le time by.** re
4140: 74 75 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68  turning the N-th
4150: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70   compile time op
4160: 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49  tion string.  ^I
4170: 66 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  f N is out of ra
4180: 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  nge,.** sqlite3_
4190: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
41a0: 74 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55  t() returns a NU
41b0: 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68  LL pointer.  ^Th
41c0: 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72  e SQLITE_ .** pr
41d0: 65 66 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20  efix is omitted 
41e0: 66 72 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73  from any strings
41f0: 20 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a   returned by .**
4200: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
4210: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a  option_get()..**
4220: 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72  .** ^Support for
4230: 20 74 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20   the diagnostic 
4240: 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65  functions sqlite
4250: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
4260: 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71  used().** and sq
4270: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
4280: 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65  ion_get() may be
4290: 20 6f 6d 69 74 74 65 64 20 62 79 20 73 70 65 63   omitted by spec
42a0: 69 66 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b  ifying the .** [
42b0: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50  SQLITE_OMIT_COMP
42c0: 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d  ILEOPTION_DIAGS]
42d0: 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69   option at compi
42e0: 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53  le time..**.** S
42f0: 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e  ee also: SQL fun
4300: 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63  ctions [sqlite_c
4310: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
4320: 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  d()] and.** [sql
4330: 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  ite_compileoptio
4340: 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65  n_get()] and the
4350: 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e   [compile_option
4360: 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69  s pragma]..*/.#i
4370: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  fndef SQLITE_OMI
4380: 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f  T_COMPILEOPTION_
4390: 44 49 41 47 53 0a 53 51 4c 49 54 45 5f 41 50 49  DIAGS.SQLITE_API
43a0: 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
43b0: 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  ALL sqlite3_comp
43c0: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63  ileoption_used(c
43d0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e  onst char *zOptN
43e0: 61 6d 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ame);.SQLITE_API
43f0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c   const char *SQL
4400: 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
4410: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
4420: 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65  n_get(int N);.#e
4430: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
4440: 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65  3REF: Test To Se
4450: 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 79  e If The Library
4460: 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a   Is Threadsafe.*
4470: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
4480: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66  3_threadsafe() f
4490: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
44a0: 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79  zero if and only
44b0: 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61   if.** SQLite wa
44c0: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
44d0: 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d  mutexing code om
44e0: 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68 65  itted due to the
44f0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
4500: 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d  ADSAFE] compile-
4510: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e  time option bein
4520: 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a  g set to 0..**.*
4530: 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20  * SQLite can be 
4540: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72  compiled with or
4550: 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73   without mutexes
4560: 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b  .  When.** the [
4570: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
4580: 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  E] C preprocesso
4590: 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20  r macro is 1 or 
45a0: 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  2, mutexes.** ar
45b0: 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51  e enabled and SQ
45c0: 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73 61  Lite is threadsa
45d0: 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a  fe.  When the.**
45e0: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
45f0: 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c  AFE] macro is 0,
4600: 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73   .** the mutexes
4610: 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57   are omitted.  W
4620: 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78  ithout the mutex
4630: 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61  es, it is not sa
4640: 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c  fe.** to use SQL
4650: 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79  ite concurrently
4660: 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20   from more than 
4670: 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a  one thread..**.*
4680: 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78  * Enabling mutex
4690: 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73  es incurs a meas
46a0: 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e  urable performan
46b0: 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53  ce penalty..** S
46c0: 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f 66  o if speed is of
46d0: 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e   utmost importan
46e0: 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e  ce, it makes sen
46f0: 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a  se to disable.**
4700: 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42   the mutexes.  B
4710: 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73  ut for maximum s
4720: 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73  afety, mutexes s
4730: 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64  hould be enabled
4740: 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
4750: 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f  t behavior is fo
4760: 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20  r mutexes to be 
4770: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  enabled..**.** T
4780: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
4790: 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e 20  n be used by an 
47a0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d  application to m
47b0: 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68  ake sure that th
47c0: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  e.** version of 
47d0: 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69  SQLite that it i
47e0: 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73  s linking agains
47f0: 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  t was compiled w
4800: 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72  ith.** the desir
4810: 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68  ed setting of th
4820: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
4830: 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  SAFE] macro..**.
4840: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
4850: 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f  e only reports o
4860: 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69  n the compile-ti
4870: 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67  me mutex setting
4880: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  .** of the [SQLI
4890: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66  TE_THREADSAFE] f
48a0: 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20  lag.  If SQLite 
48b0: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
48c0: 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41  .** SQLITE_THREA
48d0: 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68  DSAFE=1 or =2 th
48e0: 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 65  en mutexes are e
48f0: 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
4900: 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20  t but.** can be 
4910: 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c  fully or partial
4920: 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e  ly disabled usin
4930: 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  g a call to [sql
4940: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a  ite3_config()].*
4950: 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62 73  * with the verbs
4960: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
4970: 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b  SINGLETHREAD], [
4980: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
4990: 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f  LTITHREAD],.** o
49a0: 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
49b0: 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20 5e  _SERIALIZED].  ^
49c0: 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75  (The return valu
49d0: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69  e of the.** sqli
49e0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
49f0: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20   function shows 
4a00: 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65  only the compile
4a10: 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66  -time setting of
4a20: 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74  .** thread safet
4a30: 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74  y, not any run-t
4a40: 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ime changes to t
4a50: 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65  hat setting made
4a60: 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   by.** sqlite3_c
4a70: 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65  onfig(). In othe
4a80: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74  r words, the ret
4a90: 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
4aa0: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
4ab0: 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e  e().** is unchan
4ac0: 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20  ged by calls to 
4ad0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
4ae0: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68  .)^.**.** See th
4af0: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
4b00: 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  e] documentation
4b10: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
4b20: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
4b30: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
4b40: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
4b50: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
4b60: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
4b70: 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
4b80: 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e  e Connection Han
4b90: 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  dle.** KEYWORDS:
4ba0: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   {database conne
4bb0: 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65  ction} {database
4bc0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a   connections}.**
4bd0: 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51  .** Each open SQ
4be0: 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73  Lite database is
4bf0: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
4c00: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
4c10: 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74  instance of.** t
4c20: 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74  he opaque struct
4c30: 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74  ure named "sqlit
4c40: 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66  e3".  It is usef
4c50: 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61  ul to think of a
4c60: 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69  n sqlite3.** poi
4c70: 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63  nter as an objec
4c80: 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  t.  The [sqlite3
4c90: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
4ca0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e  e3_open16()], an
4cb0: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d.** [sqlite3_op
4cc0: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
4cd0: 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73  ces are its cons
4ce0: 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73  tructors, and [s
4cf0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a  qlite3_close()].
4d00: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
4d10: 63 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20  close_v2()] are 
4d20: 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e  its destructors.
4d30: 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79    There are many
4d40: 20 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66   other.** interf
4d50: 61 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a  aces (such as.**
4d60: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
4d70: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
4d80: 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
4d90: 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  n()], and.** [sq
4da0: 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
4db0: 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75  ut()] to name bu
4dc0: 74 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72  t three) that ar
4dd0: 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a  e methods on an.
4de0: 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63  ** sqlite3 objec
4df0: 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  t..*/.typedef st
4e00: 72 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c  ruct sqlite3 sql
4e10: 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ite3;../*.** CAP
4e20: 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e  I3REF: 64-Bit In
4e30: 74 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b  teger Types.** K
4e40: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f  EYWORDS: sqlite_
4e50: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e  int64 sqlite_uin
4e60: 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73  t64.**.** Becaus
4e70: 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72  e there is no cr
4e80: 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79  oss-platform way
4e90: 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62   to specify 64-b
4ea0: 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73  it integer types
4eb0: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75  .** SQLite inclu
4ec0: 64 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72  des typedefs for
4ed0: 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61   64-bit signed a
4ee0: 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  nd unsigned inte
4ef0: 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  gers..**.** The 
4f00: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e  sqlite3_int64 an
4f10: 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  d sqlite3_uint64
4f20: 20 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72   are the preferr
4f30: 65 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69  ed type definiti
4f40: 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ons..** The sqli
4f50: 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  te_int64 and sql
4f60: 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73  ite_uint64 types
4f70: 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66   are supported f
4f80: 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20  or backwards.** 
4f90: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e  compatibility on
4fa0: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
4fb0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
4fc0: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79   sqlite_int64 ty
4fd0: 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e  pes can store in
4fe0: 74 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20  teger values.** 
4ff0: 62 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32  between -9223372
5000: 30 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64  036854775808 and
5010: 20 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37   +92233720368547
5020: 37 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e  75807 inclusive.
5030: 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65    ^The.** sqlite
5040: 33 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  3_uint64 and sql
5050: 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73  ite_uint64 types
5060: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67   can store integ
5070: 65 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65  er values .** be
5080: 74 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34  tween 0 and +184
5090: 34 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31  4674407370955161
50a0: 35 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a  5 inclusive..*/.
50b0: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e  #ifdef SQLITE_IN
50c0: 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64  T64_TYPE.  typed
50d0: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ef SQLITE_INT64_
50e0: 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36  TYPE sqlite_int6
50f0: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
5100: 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54  igned SQLITE_INT
5110: 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75  64_TYPE sqlite_u
5120: 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 66  int64;.#elif def
5130: 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c  ined(_MSC_VER) |
5140: 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c  | defined(__BORL
5150: 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65  ANDC__).  typede
5160: 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  f __int64 sqlite
5170: 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65  _int64;.  typede
5180: 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74  f unsigned __int
5190: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  64 sqlite_uint64
51a0: 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65  ;.#else.  typede
51b0: 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20  f long long int 
51c0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
51d0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
51e0: 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73   long long int s
51f0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
5200: 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c  ndif.typedef sql
5210: 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  ite_int64 sqlite
5220: 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66  3_int64;.typedef
5230: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73   sqlite_uint64 s
5240: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a  qlite3_uint64;..
5250: 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69  /*.** If compili
5260: 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73  ng for a process
5270: 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c  or that lacks fl
5280: 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70  oating point sup
5290: 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74  port,.** substit
52a0: 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20  ute integer for 
52b0: 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a  floating-point..
52c0: 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  */.#ifdef SQLITE
52d0: 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50  _OMIT_FLOATING_P
52e0: 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f  OINT.# define do
52f0: 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  uble sqlite3_int
5300: 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  64.#endif../*.**
5310: 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69   CAPI3REF: Closi
5320: 6e 67 20 41 20 44 61 74 61 62 61 73 65 20 43 6f  ng A Database Co
5330: 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 44 45 53 54  nnection.** DEST
5340: 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a  RUCTOR: sqlite3.
5350: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
5360: 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73  e3_close() and s
5370: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
5380: 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64  ) routines are d
5390: 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20 66 6f  estructors.** fo
53a0: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  r the [sqlite3] 
53b0: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c  object..** ^Call
53c0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f  s to sqlite3_clo
53d0: 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  se() and sqlite3
53e0: 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 65 74 75  _close_v2() retu
53f0: 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  rn [SQLITE_OK] i
5400: 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  f.** the [sqlite
5410: 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73 75 63  3] object is suc
5420: 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f  cessfully destro
5430: 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f  yed and all asso
5440: 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f 75 72  ciated.** resour
5450: 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63 61  ces are dealloca
5460: 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ted..**.** ^If t
5470: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
5480: 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f 63 69  ection is associ
5490: 61 74 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61  ated with unfina
54a0: 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 0a 2a  lized prepared.*
54b0: 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 72 20  * statements or 
54c0: 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74  unfinished sqlit
54d0: 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 63 74  e3_backup object
54e0: 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  s then sqlite3_c
54f0: 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c  lose().** will l
5500: 65 61 76 65 20 74 68 65 20 64 61 74 61 62 61 73  eave the databas
5510: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65  e connection ope
5520: 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51  n and return [SQ
5530: 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e  LITE_BUSY]..** ^
5540: 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  If sqlite3_close
5550: 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20  _v2() is called 
5560: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
5570: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
5580: 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f 6f 72 20 75  ents.** and/or u
5590: 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65  nfinished sqlite
55a0: 33 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20  3_backups, then 
55b0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
55c0: 6e 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a  nection becomes.
55d0: 2a 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22  ** an unusable "
55e0: 7a 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69  zombie" which wi
55f0: 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ll automatically
5600: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
5610: 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74  when the.** last
5620: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
5630: 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64  ent is finalized
5640: 20 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c   or the last sql
5650: 69 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a  ite3_backup is.*
5660: 2a 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65  * finished.  The
5670: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76   sqlite3_close_v
5680: 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  2() interface is
5690: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
56a0: 65 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c  e with.** host l
56b0: 61 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72  anguages that ar
56c0: 65 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63  e garbage collec
56d0: 74 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74  ted, and where t
56e0: 68 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63  he order in whic
56f0: 68 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73  h.** destructors
5700: 20 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61   are called is a
5710: 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20  rbitrary..**.** 
5720: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  Applications sho
5730: 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  uld [sqlite3_fin
5740: 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65  alize | finalize
5750: 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20  ] all [prepared 
5760: 73 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20  statements],.** 
5770: 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c  [sqlite3_blob_cl
5780: 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c  ose | close] all
5790: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c   [BLOB handles],
57a0: 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   and .** [sqlite
57b0: 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20  3_backup_finish 
57c0: 7c 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73  | finish] all [s
57d0: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
57e0: 62 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65  bjects associate
57f0: 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73  d.** with the [s
5800: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70  qlite3] object p
5810: 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69  rior to attempti
5820: 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20  ng to close the 
5830: 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20  object.  ^If.** 
5840: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
5850: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20  () is called on 
5860: 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
5870: 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69  ection] that sti
5880: 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61  ll has.** outsta
5890: 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20  nding [prepared 
58a0: 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c  statements], [BL
58b0: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64  OB handles], and
58c0: 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  /or.** [sqlite3_
58d0: 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20  backup] objects 
58e0: 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 20  then it returns 
58f0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 61 6e 64 20  [SQLITE_OK] and 
5900: 74 68 65 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e  the deallocation
5910: 0a 2a 2a 20 6f 66 20 72 65 73 6f 75 72 63 65 73  .** of resources
5920: 20 69 73 20 64 65 66 65 72 72 65 64 20 75 6e 74   is deferred unt
5930: 69 6c 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64  il all [prepared
5940: 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42   statements], [B
5950: 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a  LOB handles],.**
5960: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 61   and [sqlite3_ba
5970: 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 72  ckup] objects ar
5980: 65 20 61 6c 73 6f 20 64 65 73 74 72 6f 79 65 64  e also destroyed
5990: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b  ..**.** ^If an [
59a0: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
59b0: 69 73 20 64 65 73 74 72 6f 79 65 64 20 77 68 69  is destroyed whi
59c0: 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  le a transaction
59d0: 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65   is open,.** the
59e0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
59f0: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f  automatically ro
5a00: 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a  lled back..**.**
5a10: 20 54 68 65 20 43 20 70 61 72 61 6d 65 74 65 72   The C parameter
5a20: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f   to [sqlite3_clo
5a30: 73 65 28 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69  se(C)] and [sqli
5a40: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d  te3_close_v2(C)]
5a50: 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68  .** must be eith
5a60: 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  er a NULL.** poi
5a70: 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69  nter or an [sqli
5a80: 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e  te3] object poin
5a90: 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ter obtained.** 
5aa0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70  from [sqlite3_op
5ab0: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
5ac0: 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a  open16()], or.**
5ad0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
5ae0: 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72  2()], and not pr
5af0: 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e  eviously closed.
5b00: 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c  .** ^Calling sql
5b10: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20  ite3_close() or 
5b20: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
5b30: 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  () with a NULL p
5b40: 6f 69 6e 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65  ointer.** argume
5b50: 6e 74 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  nt is a harmless
5b60: 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 54   no-op..*/.SQLIT
5b70: 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
5b80: 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
5b90: 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a 29  _close(sqlite3*)
5ba0: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
5bb0: 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
5bc0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
5bd0: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
5be0: 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20  ** The type for 
5bf0: 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
5c00: 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  ion..** This is 
5c10: 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65  legacy and depre
5c20: 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e  cated.  It is in
5c30: 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f  cluded for histo
5c40: 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69  rical.** compati
5c50: 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f  bility and is no
5c60: 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f  t documented..*/
5c70: 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73  .typedef int (*s
5c80: 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29  qlite3_callback)
5c90: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
5ca0: 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a  *, char**);../*.
5cb0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65  ** CAPI3REF: One
5cc0: 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63  -Step Query Exec
5cd0: 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a  ution Interface.
5ce0: 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
5cf0: 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e3.**.** The sql
5d00: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65  ite3_exec() inte
5d10: 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65  rface is a conve
5d20: 6e 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61  nience wrapper a
5d30: 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  round.** [sqlite
5d40: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
5d50: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
5d60: 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
5d70: 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20  finalize()],.** 
5d80: 74 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61  that allows an a
5d90: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75  pplication to ru
5da0: 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65  n multiple state
5db0: 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20  ments of SQL.** 
5dc0: 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74  without having t
5dd0: 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43  o use a lot of C
5de0: 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54   code. .**.** ^T
5df0: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
5e00: 29 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73  ) interface runs
5e10: 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54   zero or more UT
5e20: 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20  F-8 encoded,.** 
5e30: 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
5e40: 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
5e50: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74  s passed into it
5e60: 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a  s 2nd argument,.
5e70: 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78  ** in the contex
5e80: 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  t of the [databa
5e90: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70  se connection] p
5ea0: 61 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20  assed in as its 
5eb0: 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e  1st.** argument.
5ec0: 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61    ^If the callba
5ed0: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74  ck function of t
5ee0: 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20  he 3rd argument 
5ef0: 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  to.** sqlite3_ex
5f00: 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ec() is not NULL
5f10: 2c 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76  , then it is inv
5f20: 6f 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65  oked for each re
5f30: 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69  sult row.** comi
5f40: 6e 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76  ng out of the ev
5f50: 61 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74  aluated SQL stat
5f60: 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74  ements.  ^The 4t
5f70: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  h argument to.**
5f80: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
5f90: 69 73 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75  is relayed throu
5fa0: 67 68 20 74 6f 20 74 68 65 20 31 73 74 20 61 72  gh to the 1st ar
5fb0: 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a  gument of each.*
5fc0: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63  * callback invoc
5fd0: 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20  ation.  ^If the 
5fe0: 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72  callback pointer
5ff0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
6000: 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74  ().** is NULL, t
6010: 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20  hen no callback 
6020: 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20  is ever invoked 
6030: 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20  and result rows 
6040: 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a  are.** ignored..
6050: 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72  **.** ^If an err
6060: 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20  or occurs while 
6070: 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53  evaluating the S
6080: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61  QL statements pa
6090: 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  ssed into.** sql
60a0: 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65  ite3_exec(), the
60b0: 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74  n execution of t
60c0: 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65  he current state
60d0: 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a  ment stops and.*
60e0: 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73 74 61  * subsequent sta
60f0: 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70  tements are skip
6100: 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74  ped.  ^If the 5t
6110: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
6120: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
6130: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
6140: 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73  n any error mess
6150: 61 67 65 20 69 73 20 77 72 69 74 74 65 6e 20 69  age is written i
6160: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
6170: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
6180: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61  ite3_malloc()] a
6190: 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b 20 74  nd passed back t
61a0: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
61b0: 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20  arameter..** To 
61c0: 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61  avoid memory lea
61d0: 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  ks, the applicat
61e0: 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b  ion should invok
61f0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  e [sqlite3_free(
6200: 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d  )].** on error m
6210: 65 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 72  essage strings r
6220: 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20  eturned through 
6230: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
6240: 72 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r of.** sqlite3_
6250: 65 78 65 63 28 29 20 61 66 74 65 72 20 74 68 65  exec() after the
6260: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
6270: 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67  tring is no long
6280: 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49  er needed..** ^I
6290: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
62a0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
62b0: 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c  xec() is not NUL
62c0: 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a  L and no errors.
62d0: 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 73  ** occur, then s
62e0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 73 65  qlite3_exec() se
62f0: 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 69  ts the pointer i
6300: 6e 20 69 74 73 20 35 74 68 20 70 61 72 61 6d 65  n its 5th parame
6310: 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62  ter to.** NULL b
6320: 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
6330: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71  .**.** ^If an sq
6340: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
6350: 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
6360: 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c 69  n-zero, the sqli
6370: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f  te3_exec().** ro
6380: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51  utine returns SQ
6390: 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74 68 6f  LITE_ABORT witho
63a0: 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  ut invoking the 
63b0: 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 61  callback again a
63c0: 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 75  nd.** without ru
63d0: 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73 65 71  nning any subseq
63e0: 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65  uent SQL stateme
63f0: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
6400: 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  2nd argument to 
6410: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  the sqlite3_exec
6420: 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  () callback func
6430: 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e  tion is the.** n
6440: 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
6450: 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20   in the result. 
6460: 20 5e 54 68 65 20 33 72 64 20 61 72 67 75 6d 65   ^The 3rd argume
6470: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
6480: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c  3_exec().** call
6490: 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79  back is an array
64a0: 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
64b0: 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 64  strings obtained
64c0: 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b   as if from.** [
64d0: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
64e0: 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20  ext()], one for 
64f0: 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49  each column.  ^I
6500: 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20  f an element of 
6510: 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  a.** result row 
6520: 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  is NULL then the
6530: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73   corresponding s
6540: 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f  tring pointer fo
6550: 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33  r the.** sqlite3
6560: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
6570: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
6580: 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72  er.  ^The 4th ar
6590: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a  gument to the.**
65a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
65b0: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61  callback is an a
65c0: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
65d0: 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72   to strings wher
65e0: 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20  e each.** entry 
65f0: 72 65 70 72 65 73 65 6e 74 73 20 74 68 65 20 6e  represents the n
6600: 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e  ame of correspon
6610: 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c 75  ding result colu
6620: 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a  mn as obtained.*
6630: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
6640: 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a  column_name()]..
6650: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e  **.** ^If the 2n
6660: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
6670: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
6680: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
6690: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
66a0: 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
66b0: 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74  , or a pointer t
66c0: 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c  hat contains onl
66d0: 79 20 77 68 69 74 65 73 70 61 63 65 20 61 6e 64  y whitespace and
66e0: 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d  /or .** SQL comm
66f0: 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51  ents, then no SQ
6700: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
6710: 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74   evaluated and t
6720: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  he database.** i
6730: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a  s not changed..*
6740: 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69 6f 6e  *.** Restriction
6750: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
6760: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
6770: 61 74 69 6f 6e 20 6d 75 73 74 20 65 6e 73 75 72  ation must ensur
6780: 65 20 74 68 61 74 20 74 68 65 20 31 73 74 20 70  e that the 1st p
6790: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
67a0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20  te3_exec().**   
67b0: 20 20 20 69 73 20 61 20 76 61 6c 69 64 20 61 6e     is a valid an
67c0: 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65  d open [database
67d0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
67e0: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
67f0: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63  ation must not c
6800: 6c 6f 73 65 20 74 68 65 20 5b 64 61 74 61 62 61  lose the [databa
6810: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
6820: 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20  pecified by.**  
6830: 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72 61      the 1st para
6840: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
6850: 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71  _exec() while sq
6860: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
6870: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e  running..** <li>
6880: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
6890: 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79   must not modify
68a0: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
68b0: 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20 69  nt text passed i
68c0: 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20  nto.**      the 
68d0: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
68e0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
68f0: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78  while sqlite3_ex
6900: 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ec() is running.
6910: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c  .** </ul>.*/.SQL
6920: 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
6930: 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
6940: 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74  e3_exec(.  sqlit
6950: 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20  e3*,            
6960: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6970: 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
6980: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
6990: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20  onst char *sql, 
69a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
69b0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c            /* SQL
69c0: 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
69d0: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c   */.  int (*call
69e0: 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  back)(void*,int,
69f0: 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20  char**,char**), 
6a00: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e   /* Callback fun
6a10: 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ction */.  void 
6a20: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *,              
6a30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6a40: 20 20 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67        /* 1st arg
6a50: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63  ument to callbac
6a60: 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72  k */.  char **er
6a70: 72 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 20  rmsg            
6a80: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6a90: 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77    /* Error msg w
6aa0: 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29  ritten here */.)
6ab0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
6ac0: 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a  F: Result Codes.
6ad0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65  ** KEYWORDS: {re
6ae0: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
6af0: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e  tions}.**.** Man
6b00: 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f  y SQLite functio
6b10: 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74  ns return an int
6b20: 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65  eger result code
6b30: 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68   from the set sh
6b40: 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f  own.** here in o
6b50: 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65  rder to indicate
6b60: 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c   success or fail
6b70: 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65  ure..**.** New e
6b80: 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62  rror codes may b
6b90: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
6ba0: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
6bb0: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  Lite..**.** See 
6bc0: 61 6c 73 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20  also: [extended 
6bd0: 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69  result code defi
6be0: 6e 69 74 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66  nitions].*/.#def
6bf0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20  ine SQLITE_OK   
6c00: 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53          0   /* S
6c10: 75 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74  uccessful result
6c20: 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67   */./* beginning
6c30: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
6c40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6c50: 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31  E_ERROR        1
6c60: 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20     /* SQL error 
6c70: 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62  or missing datab
6c80: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
6c90: 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20  QLITE_INTERNAL  
6ca0: 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e     2   /* Intern
6cb0: 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69  al logic error i
6cc0: 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66  n SQLite */.#def
6cd0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20  ine SQLITE_PERM 
6ce0: 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41          3   /* A
6cf0: 63 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e  ccess permission
6d00: 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69   denied */.#defi
6d10: 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ne SQLITE_ABORT 
6d20: 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61         4   /* Ca
6d30: 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72  llback routine r
6d40: 65 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72  equested an abor
6d50: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
6d60: 49 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20  ITE_BUSY        
6d70: 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61   5   /* The data
6d80: 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63  base file is loc
6d90: 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ked */.#define S
6da0: 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20  QLITE_LOCKED    
6db0: 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c     6   /* A tabl
6dc0: 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73  e in the databas
6dd0: 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23  e is locked */.#
6de0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
6df0: 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f  MEM        7   /
6e00: 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69  * A malloc() fai
6e10: 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  led */.#define S
6e20: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20  QLITE_READONLY  
6e30: 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70     8   /* Attemp
6e40: 74 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61  t to write a rea
6e50: 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a  donly database *
6e60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6e70: 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20  _INTERRUPT    9 
6e80: 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74    /* Operation t
6e90: 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c  erminated by sql
6ea0: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
6eb0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6ec0: 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30  E_IOERR       10
6ed0: 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20     /* Some kind 
6ee0: 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f  of disk I/O erro
6ef0: 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64  r occurred */.#d
6f00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52  efine SQLITE_COR
6f10: 52 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a  RUPT     11   /*
6f20: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69   The database di
6f30: 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66  sk image is malf
6f40: 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ormed */.#define
6f50: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44   SQLITE_NOTFOUND
6f60: 20 20 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e      12   /* Unkn
6f70: 6f 77 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71  own opcode in sq
6f80: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
6f90: 6f 6c 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ol() */.#define 
6fa0: 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20  SQLITE_FULL     
6fb0: 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72     13   /* Inser
6fc0: 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61  tion failed beca
6fd0: 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73 20  use database is 
6fe0: 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  full */.#define 
6ff0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
7000: 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c     14   /* Unabl
7010: 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61  e to open the da
7020: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23  tabase file */.#
7030: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
7040: 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f  OTOCOL    15   /
7050: 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20  * Database lock 
7060: 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a  protocol error *
7070: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
7080: 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 20  _EMPTY       16 
7090: 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73    /* Database is
70a0: 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e   empty */.#defin
70b0: 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20  e SQLITE_SCHEMA 
70c0: 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65       17   /* The
70d0: 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
70e0: 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66   changed */.#def
70f0: 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49  ine SQLITE_TOOBI
7100: 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53  G      18   /* S
7110: 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78  tring or BLOB ex
7120: 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74  ceeds size limit
7130: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
7140: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31  TE_CONSTRAINT  1
7150: 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65  9   /* Abort due
7160: 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76   to constraint v
7170: 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66  iolation */.#def
7180: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41  ine SQLITE_MISMA
7190: 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44  TCH    20   /* D
71a0: 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63  ata type mismatc
71b0: 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  h */.#define SQL
71c0: 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20  ITE_MISUSE      
71d0: 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20  21   /* Library 
71e0: 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79  used incorrectly
71f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
7200: 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32  TE_NOLFS       2
7210: 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66  2   /* Uses OS f
7220: 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70  eatures not supp
7230: 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f  orted on host */
7240: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7250: 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20 20  AUTH        23  
7260: 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f   /* Authorizatio
7270: 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66  n denied */.#def
7280: 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41  ine SQLITE_FORMA
7290: 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41  T      24   /* A
72a0: 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61 73  uxiliary databas
72b0: 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a  e format error *
72c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
72d0: 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35 20  _RANGE       25 
72e0: 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74    /* 2nd paramet
72f0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
7300: 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20  nd out of range 
7310: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
7320: 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36  E_NOTADB      26
7330: 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65     /* File opene
7340: 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20  d that is not a 
7350: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f  database file */
7360: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7370: 4e 4f 54 49 43 45 20 20 20 20 20 20 32 37 20 20  NOTICE      27  
7380: 20 2f 2a 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e   /* Notification
7390: 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c  s from sqlite3_l
73a0: 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  og() */.#define 
73b0: 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 20  SQLITE_WARNING  
73c0: 20 20 20 32 38 20 20 20 2f 2a 20 57 61 72 6e 69     28   /* Warni
73d0: 6e 67 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ngs from sqlite3
73e0: 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e  _log() */.#defin
73f0: 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20  e SQLITE_ROW    
7400: 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c       100  /* sql
7410: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
7420: 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64  another row read
7430: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
7440: 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20  ITE_DONE        
7450: 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  101  /* sqlite3_
7460: 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73  step() has finis
7470: 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f  hed executing */
7480: 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72  ./* end-of-error
7490: 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  -codes */../*.**
74a0: 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e   CAPI3REF: Exten
74b0: 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
74c0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65  .** KEYWORDS: {e
74d0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
74e0: 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d  ode definitions}
74f0: 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65  .**.** In its de
7500: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
7510: 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20  ion, SQLite API 
7520: 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
7530: 6f 6e 65 20 6f 66 20 33 30 20 69 6e 74 65 67 65  one of 30 intege
7540: 72 0a 2a 2a 20 5b 72 65 73 75 6c 74 20 63 6f 64  r.** [result cod
7550: 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65  es].  However, e
7560: 78 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68  xperience has sh
7570: 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66  own that many of
7580: 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74  .** these result
7590: 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63   codes are too c
75a0: 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20  oarse-grained.  
75b0: 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76  They do not prov
75c0: 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69  ide as.** much i
75d0: 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
75e0: 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f   problems as pro
75f0: 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c  grammers might l
7600: 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f  ike.  In an effo
7610: 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73  rt to.** address
7620: 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72   this, newer ver
7630: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
7640: 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61  (version 3.3.8 a
7650: 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64  nd later) includ
7660: 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72  e.** support for
7670: 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75   additional resu
7680: 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72  lt codes that pr
7690: 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69  ovide more detai
76a0: 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  led information.
76b0: 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e  ** about errors.
76c0: 20 54 68 65 73 65 20 5b 65 78 74 65 6e 64 65 64   These [extended
76d0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 61   result codes] a
76e0: 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  re enabled or di
76f0: 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70  sabled.** on a p
7700: 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  er database conn
7710: 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69  ection basis usi
7720: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
7730: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
7740: 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e  lt_codes()] API.
7750: 20 20 4f 72 2c 20 74 68 65 20 65 78 74 65 6e 64    Or, the extend
7760: 65 64 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74  ed code for.** t
7770: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
7780: 72 72 6f 72 20 63 61 6e 20 62 65 20 6f 62 74 61  rror can be obta
7790: 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ined using.** [s
77a0: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
77b0: 65 72 72 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23  errcode()]..*/.#
77c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
77d0: 45 52 52 5f 52 45 41 44 20 20 20 20 20 20 20 20  ERR_READ        
77e0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
77f0: 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ERR | (1<<8)).#d
7800: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
7810: 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20  RR_SHORT_READ   
7820: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
7830: 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  RR | (2<<8)).#de
7840: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
7850: 52 5f 57 52 49 54 45 20 20 20 20 20 20 20 20 20  R_WRITE         
7860: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
7870: 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66  R | (3<<8)).#def
7880: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
7890: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 20  _FSYNC          
78a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
78b0: 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69   | (4<<8)).#defi
78c0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
78d0: 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20  DIR_FSYNC       
78e0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
78f0: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
7900: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54  e SQLITE_IOERR_T
7910: 52 55 4e 43 41 54 45 20 20 20 20 20 20 20 20 20  RUNCATE         
7920: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
7930: 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (6<<8)).#define
7940: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53   SQLITE_IOERR_FS
7950: 54 41 54 20 20 20 20 20 20 20 20 20 20 20 20 20  TAT             
7960: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
7970: 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (7<<8)).#define 
7980: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c  SQLITE_IOERR_UNL
7990: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28  OCK            (
79a0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
79b0: 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  8<<8)).#define S
79c0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f  QLITE_IOERR_RDLO
79d0: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53  CK            (S
79e0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39  QLITE_IOERR | (9
79f0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7a00: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54  LITE_IOERR_DELET
7a10: 45 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  E            (SQ
7a20: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30  LITE_IOERR | (10
7a30: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7a40: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
7a50: 45 44 20 20 20 20 20 20 20 20 20 20 20 28 53 51  ED           (SQ
7a60: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31  LITE_IOERR | (11
7a70: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7a80: 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d  LITE_IOERR_NOMEM
7a90: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
7aa0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32  LITE_IOERR | (12
7ab0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7ac0: 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53  LITE_IOERR_ACCES
7ad0: 53 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  S            (SQ
7ae0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33  LITE_IOERR | (13
7af0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7b00: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b  LITE_IOERR_CHECK
7b10: 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51  RESERVEDLOCK (SQ
7b20: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34  LITE_IOERR | (14
7b30: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7b40: 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20  LITE_IOERR_LOCK 
7b50: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
7b60: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35  LITE_IOERR | (15
7b70: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7b80: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45  LITE_IOERR_CLOSE
7b90: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
7ba0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36  LITE_IOERR | (16
7bb0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7bc0: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43  LITE_IOERR_DIR_C
7bd0: 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28 53 51  LOSE         (SQ
7be0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37  LITE_IOERR | (17
7bf0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7c00: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50  LITE_IOERR_SHMOP
7c10: 45 4e 20 20 20 20 20 20 20 20 20 20 20 28 53 51  EN           (SQ
7c20: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38  LITE_IOERR | (18
7c30: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7c40: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49  LITE_IOERR_SHMSI
7c50: 5a 45 20 20 20 20 20 20 20 20 20 20 20 28 53 51  ZE           (SQ
7c60: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39  LITE_IOERR | (19
7c70: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7c80: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f  LITE_IOERR_SHMLO
7c90: 43 4b 20 20 20 20 20 20 20 20 20 20 20 28 53 51  CK           (SQ
7ca0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30  LITE_IOERR | (20
7cb0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7cc0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41  LITE_IOERR_SHMMA
7cd0: 50 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  P            (SQ
7ce0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 31  LITE_IOERR | (21
7cf0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7d00: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20  LITE_IOERR_SEEK 
7d10: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
7d20: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 32  LITE_IOERR | (22
7d30: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7d40: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54  LITE_IOERR_DELET
7d50: 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28 53 51  E_NOENT      (SQ
7d60: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 33  LITE_IOERR | (23
7d70: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7d80: 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20  LITE_IOERR_MMAP 
7d90: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
7da0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 34  LITE_IOERR | (24
7db0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7dc0: 4c 49 54 45 5f 49 4f 45 52 52 5f 47 45 54 54 45  LITE_IOERR_GETTE
7dd0: 4d 50 50 41 54 48 20 20 20 20 20 20 20 28 53 51  MPPATH       (SQ
7de0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 35  LITE_IOERR | (25
7df0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7e00: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50  LITE_IOERR_CONVP
7e10: 41 54 48 20 20 20 20 20 20 20 20 20 20 28 53 51  ATH          (SQ
7e20: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 36  LITE_IOERR | (26
7e30: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7e40: 4c 49 54 45 5f 49 4f 45 52 52 5f 56 4e 4f 44 45  LITE_IOERR_VNODE
7e50: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
7e60: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 37  LITE_IOERR | (27
7e70: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7e80: 4c 49 54 45 5f 49 4f 45 52 52 5f 41 55 54 48 20  LITE_IOERR_AUTH 
7e90: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
7ea0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 38  LITE_IOERR | (28
7eb0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7ec0: 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52  LITE_LOCKED_SHAR
7ed0: 45 44 43 41 43 48 45 20 20 20 20 20 20 28 53 51  EDCACHE      (SQ
7ee0: 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28  LITE_LOCKED |  (
7ef0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
7f00: 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56  QLITE_BUSY_RECOV
7f10: 45 52 59 20 20 20 20 20 20 20 20 20 20 20 28 53  ERY           (S
7f20: 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20  QLITE_BUSY   |  
7f30: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
7f40: 53 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e 41 50  SQLITE_BUSY_SNAP
7f50: 53 48 4f 54 20 20 20 20 20 20 20 20 20 20 20 28  SHOT           (
7f60: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20  SQLITE_BUSY   | 
7f70: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
7f80: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
7f90: 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20 20  _NOTEMPDIR      
7fa0: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  (SQLITE_CANTOPEN
7fb0: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
7fc0: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
7fd0: 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20 20  EN_ISDIR        
7fe0: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
7ff0: 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  EN | (2<<8)).#de
8000: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
8010: 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20  OPEN_FULLPATH   
8020: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54      (SQLITE_CANT
8030: 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23  OPEN | (3<<8)).#
8040: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
8050: 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20  NTOPEN_CONVPATH 
8060: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
8070: 4e 54 4f 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29  NTOPEN | (4<<8))
8080: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8090: 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20  CORRUPT_VTAB    
80a0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
80b0: 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29  CORRUPT | (1<<8)
80c0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
80d0: 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45  _READONLY_RECOVE
80e0: 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  RY       (SQLITE
80f0: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c  _READONLY | (1<<
8100: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
8110: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54  TE_READONLY_CANT
8120: 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49  LOCK       (SQLI
8130: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32  TE_READONLY | (2
8140: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
8150: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f  LITE_READONLY_RO
8160: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53 51  LLBACK       (SQ
8170: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  LITE_READONLY | 
8180: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
8190: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
81a0: 44 42 4d 4f 56 45 44 20 20 20 20 20 20 20 20 28  DBMOVED        (
81b0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
81c0: 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (4<<8)).#defin
81d0: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52  e SQLITE_ABORT_R
81e0: 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20  OLLBACK         
81f0: 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c   (SQLITE_ABORT |
8200: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
8210: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
8220: 4e 54 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20  NT_CHECK        
8230: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
8240: 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  NT | (1<<8)).#de
8250: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
8260: 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f  TRAINT_COMMITHOO
8270: 4b 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  K   (SQLITE_CONS
8280: 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29  TRAINT | (2<<8))
8290: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
82a0: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49  CONSTRAINT_FOREI
82b0: 47 4e 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f  GNKEY   (SQLITE_
82c0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c  CONSTRAINT | (3<
82d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
82e0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46  ITE_CONSTRAINT_F
82f0: 55 4e 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c  UNCTION     (SQL
8300: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
8310: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
8320: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
8330: 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20  NT_NOTNULL      
8340: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
8350: 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65  NT | (5<<8)).#de
8360: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
8370: 54 52 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45  TRAINT_PRIMARYKE
8380: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  Y   (SQLITE_CONS
8390: 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29  TRAINT | (6<<8))
83a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
83b0: 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47  CONSTRAINT_TRIGG
83c0: 45 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  ER      (SQLITE_
83d0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c  CONSTRAINT | (7<
83e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
83f0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55  ITE_CONSTRAINT_U
8400: 4e 49 51 55 45 20 20 20 20 20 20 20 28 53 51 4c  NIQUE       (SQL
8410: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
8420: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (8<<8)).#define
8430: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
8440: 4e 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20  NT_VTAB         
8450: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
8460: 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  NT | (9<<8)).#de
8470: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
8480: 54 52 41 49 4e 54 5f 52 4f 57 49 44 20 20 20 20  TRAINT_ROWID    
8490: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
84a0: 54 52 41 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29  TRAINT |(10<<8))
84b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
84c0: 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 57  NOTICE_RECOVER_W
84d0: 41 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  AL      (SQLITE_
84e0: 4e 4f 54 49 43 45 20 7c 20 28 31 3c 3c 38 29 29  NOTICE | (1<<8))
84f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8500: 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 52  NOTICE_RECOVER_R
8510: 4f 4c 4c 42 41 43 4b 20 28 53 51 4c 49 54 45 5f  OLLBACK (SQLITE_
8520: 4e 4f 54 49 43 45 20 7c 20 28 32 3c 3c 38 29 29  NOTICE | (2<<8))
8530: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8540: 57 41 52 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45  WARNING_AUTOINDE
8550: 58 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  X       (SQLITE_
8560: 57 41 52 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29  WARNING | (1<<8)
8570: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
8580: 5f 41 55 54 48 5f 55 53 45 52 20 20 20 20 20 20  _AUTH_USER      
8590: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
85a0: 5f 41 55 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a  _AUTH | (1<<8)).
85b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
85c0: 4b 5f 4c 4f 41 44 5f 50 45 52 4d 41 4e 45 4e 54  K_LOAD_PERMANENT
85d0: 4c 59 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4f  LY     (SQLITE_O
85e0: 4b 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a  K | (1<<8))../*.
85f0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
8600: 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e  gs For File Open
8610: 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a   Operations.**.*
8620: 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75  * These bit valu
8630: 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  es are intended 
8640: 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a  for use in the.*
8650: 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  * 3rd parameter 
8660: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
8670: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
8680: 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74  face and.** in t
8690: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
86a0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
86b0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
86c0: 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  od..*/.#define S
86d0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
86e0: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30  NLY         0x00
86f0: 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f  000001  /* Ok fo
8700: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
8710: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
8720: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
8730: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30  RITE        0x00
8740: 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f  000002  /* Ok fo
8750: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
8760: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
8770: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
8780: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  E           0x00
8790: 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f  000004  /* Ok fo
87a0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
87b0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
87c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
87d0: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30  EONCLOSE    0x00
87e0: 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f  000008  /* VFS o
87f0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
8800: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
8810: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30  SIVE        0x00
8820: 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f  000010  /* VFS o
8830: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
8840: 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50  QLITE_OPEN_AUTOP
8850: 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30  ROXY        0x00
8860: 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f  000020  /* VFS o
8870: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
8880: 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20  QLITE_OPEN_URI  
8890: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
88a0: 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f  000040  /* Ok fo
88b0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
88c0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
88d0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52  QLITE_OPEN_MEMOR
88e0: 59 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  Y           0x00
88f0: 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f  000080  /* Ok fo
8900: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
8910: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
8920: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
8930: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
8940: 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f  000100  /* VFS o
8950: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
8960: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
8970: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
8980: 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f  000200  /* VFS o
8990: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
89a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
89b0: 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30  IENT_DB     0x00
89c0: 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f  000400  /* VFS o
89d0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
89e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
89f0: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
8a00: 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f  000800  /* VFS o
8a10: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
8a20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
8a30: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
8a40: 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  001000  /* VFS o
8a50: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
8a60: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
8a70: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30  URNAL       0x00
8a80: 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  002000  /* VFS o
8a90: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
8aa0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
8ab0: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30  R_JOURNAL   0x00
8ac0: 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  004000  /* VFS o
8ad0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
8ae0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
8af0: 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30  EX          0x00
8b00: 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  008000  /* Ok fo
8b10: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
8b20: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
8b30: 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
8b40: 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30  UTEX        0x00
8b50: 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  010000  /* Ok fo
8b60: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
8b70: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
8b80: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
8b90: 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30  DCACHE      0x00
8ba0: 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  020000  /* Ok fo
8bb0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
8bc0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
8bd0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
8be0: 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30  TECACHE     0x00
8bf0: 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  040000  /* Ok fo
8c00: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
8c10: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
8c20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20  QLITE_OPEN_WAL  
8c30: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
8c40: 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  080000  /* VFS o
8c50: 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72  nly */../* Reser
8c60: 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20  ved:            
8c70: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
8c80: 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a  0F00000 */../*.*
8c90: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69  * CAPI3REF: Devi
8ca0: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69  ce Characteristi
8cb0: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65  cs.**.** The xDe
8cc0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
8cd0: 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ics method of th
8ce0: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
8cf0: 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74  thods].** object
8d00: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65   returns an inte
8d10: 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76  ger which is a v
8d20: 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a  ector of these.*
8d30: 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70  * bit values exp
8d40: 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72  ressing I/O char
8d50: 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74  acteristics of t
8d60: 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a  he mass storage.
8d70: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68  ** device that h
8d80: 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68  olds the file th
8d90: 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
8da0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72  io_methods].** r
8db0: 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20  efers to..**.** 
8dc0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
8dd0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
8de0: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
8df0: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
8e00: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
8e10: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
8e20: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
8e30: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
8e40: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
8e50: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
8e60: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
8e70: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
8e80: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
8e90: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
8ea0: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
8eb0: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
8ec0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
8ed0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
8ee0: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
8ef0: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
8f00: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
8f10: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
8f20: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
8f30: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
8f40: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
8f50: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
8f60: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
8f70: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
8f80: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
8f90: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
8fa0: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
8fb0: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
8fc0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
8fd0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
8fe0: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
8ff0: 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49  ite().  The SQLI
9000: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
9010: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f  FE_OVERWRITE pro
9020: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
9030: 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74  .** after reboot
9040: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61   following a cra
9050: 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73  sh or power loss
9060: 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73  , the only bytes
9070: 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68   in a.** file th
9080: 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20  at were written 
9090: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  at the applicati
90a0: 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68  on level might h
90b0: 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61  ave changed.** a
90c0: 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74  nd that adjacent
90d0: 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74   bytes, even byt
90e0: 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  es within the sa
90f0: 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a  me sector are.**
9100: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
9110: 65 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68  e unchanged.  Th
9120: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55  e SQLITE_IOCAP_U
9130: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
9140: 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64  OPEN.** flag ind
9150: 69 63 61 74 65 20 74 68 61 74 20 61 20 66 69 6c  icate that a fil
9160: 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65  e cannot be dele
9170: 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20  ted when open.  
9180: 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  The.** SQLITE_IO
9190: 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c  CAP_IMMUTABLE fl
91a0: 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  ag indicates tha
91b0: 74 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e  t the file is on
91c0: 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65  .** read-only me
91d0: 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62  dia and cannot b
91e0: 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62  e changed even b
91f0: 79 20 70 72 6f 63 65 73 73 65 73 20 77 69 74 68  y processes with
9200: 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69  .** elevated pri
9210: 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66  vileges..*/.#def
9220: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
9230: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20  _ATOMIC         
9240: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
9250: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
9260: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
9270: 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  2              0
9280: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e  x00000002.#defin
9290: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
92a0: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20  TOMIC1K         
92b0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
92c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
92d0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20  IOCAP_ATOMIC2K  
92e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
92f0: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
9300: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
9310: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20  MIC4K           
9320: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23      0x00000010.#
9330: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
9340: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20  CAP_ATOMIC8K    
9350: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
9360: 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51  00020.#define SQ
9370: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
9380: 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20  C16K            
9390: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65    0x00000040.#de
93a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
93b0: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20  P_ATOMIC32K     
93c0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
93d0: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  080.#define SQLI
93e0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
93f0: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  4K              
9400: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
9410: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
9420: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
9430: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
9440: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
9450: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
9460: 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78  L             0x
9470: 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65  00000400.#define
9480: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
9490: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
94a0: 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a  PEN  0x00000800.
94b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
94c0: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
94d0: 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30  VERWRITE    0x00
94e0: 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53  001000.#define S
94f0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55  QLITE_IOCAP_IMMU
9500: 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
9510: 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f     0x00002000../
9520: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
9530: 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65  ile Locking Leve
9540: 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  ls.**.** SQLite 
9550: 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73  uses one of thes
9560: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
9570: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
9580: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61  * argument to ca
9590: 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20  lls it makes to 
95a0: 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20  the xLock() and 
95b0: 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  xUnlock() method
95c0: 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69  s.** of an [sqli
95d0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
95e0: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69  object..*/.#defi
95f0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  ne SQLITE_LOCK_N
9600: 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23  ONE          0.#
9610: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
9620: 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  CK_SHARED       
9630: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
9640: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20  E_LOCK_RESERVED 
9650: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
9660: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
9670: 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  NG       3.#defi
9680: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  ne SQLITE_LOCK_E
9690: 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a  XCLUSIVE     4..
96a0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
96b0: 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20  Synchronization 
96c0: 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a  Type Flags.**.**
96d0: 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76   When SQLite inv
96e0: 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29  okes the xSync()
96f0: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a   method of an.**
9700: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
9710: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20  hods] object it 
9720: 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69  uses a combinati
9730: 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69  on of.** these i
9740: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
9750: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
9760: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  ment..**.** When
9770: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
9780: 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69  _DATAONLY flag i
9790: 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73  s used, it means
97a0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e   that the.** syn
97b0: 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79  c operation only
97c0: 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20   needs to flush 
97d0: 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f  data to mass sto
97e0: 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20  rage.  Inode.** 
97f0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64  information need
9800: 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e   not be flushed.
9810: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f   If the lower fo
9820: 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66  ur bits of the f
9830: 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c  lag.** equal SQL
9840: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c  ITE_SYNC_NORMAL,
9850: 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75   that means to u
9860: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  se normal fsync(
9870: 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20  ) semantics..** 
9880: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
9890: 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c  r bits equal SQL
98a0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74  ITE_SYNC_FULL, t
98b0: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20  hat means.** to 
98c0: 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79  use Mac OS X sty
98d0: 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74  le fullsync inst
98e0: 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a  ead of fsync()..
98f0: 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e  **.** Do not con
9900: 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f  fuse the SQLITE_
9910: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
9920: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
9930: 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74   flags.** with t
9940: 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  he [PRAGMA synch
9950: 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61  ronous]=NORMAL a
9960: 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  nd [PRAGMA synch
9970: 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20  ronous]=FULL.** 
9980: 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b  settings.  The [
9990: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67  synchronous prag
99a0: 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77  ma] determines w
99b0: 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  hen calls to the
99c0: 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65  .** xSync VFS me
99d0: 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61  thod occur and a
99e0: 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79  pplies uniformly
99f0: 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74   across all plat
9a00: 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51  forms..** The SQ
9a10: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
9a20: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
9a30: 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65  _FULL flags dete
9a40: 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65  rmine how.** ene
9a50: 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f  rgetic or rigoro
9a60: 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74  us or forceful t
9a70: 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  he sync operatio
9a80: 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e  ns are and.** on
9a90: 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72  ly make a differ
9aa0: 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20  ence on Mac OSX 
9ab0: 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20  for the default 
9ac0: 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20  SQLite code..** 
9ad0: 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53  (Third-party VFS
9ae0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
9af0: 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65   might also make
9b00: 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
9b10: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49  .** between SQLI
9b20: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
9b30: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
9b40: 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74  ULL, but among t
9b50: 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20  he.** operating 
9b60: 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79  systems natively
9b70: 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
9b80: 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f  Lite, only Mac O
9b90: 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75  SX.** cares abou
9ba0: 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65  t the difference
9bb0: 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  .).*/.#define SQ
9bc0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
9bd0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
9be0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
9bf0: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
9c00: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
9c10: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
9c20: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
9c30: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  010../*.** CAPI3
9c40: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
9c50: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
9c60: 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c  le.**.** An [sql
9c70: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
9c80: 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  t represents an 
9c90: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65  open file in the
9ca0: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66   .** [sqlite3_vf
9cb0: 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  s | OS interface
9cc0: 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69   layer].  Indivi
9cd0: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63  dual OS interfac
9ce0: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
9cf0: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e  ions will.** wan
9d00: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68  t to subclass th
9d10: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70  is object by app
9d20: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61  ending additiona
9d30: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20  l fields.** for 
9d40: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20  their own use.  
9d50: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74  The pMethods ent
9d60: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ry is a pointer 
9d70: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  to an.** [sqlite
9d80: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
9d90: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
9da0: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65  s methods for pe
9db0: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20  rforming.** I/O 
9dc0: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68  operations on th
9dd0: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a  e open file..*/.
9de0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
9df0: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69  qlite3_file sqli
9e00: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74  te3_file;.struct
9e10: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a   sqlite3_file {.
9e20: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73    const struct s
9e30: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
9e40: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a  s *pMethods;  /*
9e50: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20   Methods for an 
9e60: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a  open file */.};.
9e70: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
9e80: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69   OS Interface Fi
9e90: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f  le Virtual Metho
9ea0: 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ds Object.**.** 
9eb0: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65  Every file opene
9ec0: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
9ed0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
9ee0: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e  hod populates an
9ef0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
9f00: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d  e] object (or, m
9f10: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20  ore commonly, a 
9f20: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a  subclass of the.
9f30: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
9f40: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61  ] object) with a
9f50: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
9f60: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
9f70: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20  object..** This 
9f80: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
9f90: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  he methods used 
9fa0: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
9fb0: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  us operations.**
9fc0: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65   against the ope
9fd0: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74  n file represent
9fe0: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
9ff0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e  e3_file] object.
a000: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73  .**.** If the [s
a010: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
a020: 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68  ] method sets th
a030: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
a040: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20  Methods element 
a050: 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c  .** to a non-NUL
a060: 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
a070: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  the sqlite3_io_m
a080: 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65  ethods.xClose me
a090: 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69  thod.** may be i
a0a0: 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74  nvoked even if t
a0b0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
a0c0: 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20  xOpen] reported 
a0d0: 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20  that it failed. 
a0e0: 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79   The.** only way
a0f0: 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61   to prevent a ca
a100: 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c  ll to xClose fol
a110: 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20  lowing a failed 
a120: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
a130: 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  en].** is for th
a140: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
a150: 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65  Open] to set the
a160: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
a170: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a  ethods element.*
a180: 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  * to NULL..**.**
a190: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
a1a0: 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79  ent to xSync may
a1b0: 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   be one of [SQLI
a1c0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20  TE_SYNC_NORMAL] 
a1d0: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59  or.** [SQLITE_SY
a1e0: 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66  NC_FULL].  The f
a1f0: 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74  irst choice is t
a200: 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  he normal fsync(
a210: 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  )..** The second
a220: 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63   choice is a Mac
a230: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
a240: 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49  sync.  The [SQLI
a250: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
a260: 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65  ].** flag may be
a270: 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69   ORed in to indi
a280: 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74  cate that only t
a290: 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66  he data of the f
a2a0: 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69  ile.** and not i
a2b0: 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74  ts inode needs t
a2c0: 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a  o be synced..**.
a2d0: 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76  ** The integer v
a2e0: 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29  alues to xLock()
a2f0: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61   and xUnlock() a
a300: 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c  re one of.** <ul
a310: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
a320: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a  E_LOCK_NONE],.**
a330: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
a340: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c  CK_SHARED],.** <
a350: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
a360: 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c  _RESERVED],.** <
a370: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
a380: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a  _PENDING], or.**
a390: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
a3a0: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a  CK_EXCLUSIVE]..*
a3b0: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b  * </ul>.** xLock
a3c0: 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65  () increases the
a3d0: 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29   lock. xUnlock()
a3e0: 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c   decreases the l
a3f0: 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65  ock..** The xChe
a400: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29  ckReservedLock()
a410: 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77   method checks w
a420: 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62  hether any datab
a430: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a  ase connection,.
a440: 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69  ** either in thi
a450: 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20  s process or in 
a460: 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65  some other proce
a470: 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ss, is holding a
a480: 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45   RESERVED,.** PE
a490: 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53  NDING, or EXCLUS
a4a0: 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  IVE lock on the 
a4b0: 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e  file.  It return
a4c0: 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63  s true.** if suc
a4d0: 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20  h a lock exists 
a4e0: 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77  and false otherw
a4f0: 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ise..**.** The x
a500: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65  FileControl() me
a510: 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69  thod is a generi
a520: 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  c interface that
a530: 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a   allows custom.*
a540: 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  * VFS implementa
a550: 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c  tions to directl
a560: 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65  y control an ope
a570: 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65  n file using the
a580: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
a590: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74  e_control()] int
a5a0: 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63  erface.  The sec
a5b0: 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e  ond "op" argumen
a5c0: 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67  t is an.** integ
a5d0: 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20  er opcode.  The 
a5e0: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
a5f0: 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e  s a generic poin
a600: 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a  ter intended to.
a610: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  ** point to a st
a620: 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79  ructure that may
a630: 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e   contain argumen
a640: 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77  ts or space in w
a650: 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65  hich to.** write
a660: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20   return values. 
a670: 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20   Potential uses 
a680: 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  for xFileControl
a690: 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66  () might be.** f
a6a0: 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62  unctions to enab
a6b0: 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b  le blocking lock
a6c0: 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c  s with timeouts,
a6d0: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a   to change the.*
a6e0: 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65  * locking strate
a6f0: 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  gy (for example 
a700: 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20  to use dot-file 
a710: 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69  locks), to inqui
a720: 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20  re.** about the 
a730: 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b  status of a lock
a740: 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74  , or to break st
a750: 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20  ale locks.  The 
a760: 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72  SQLite.** core r
a770: 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f  eserves all opco
a780: 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30  des less than 10
a790: 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73  0 for its own us
a7a0: 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f  e..** A [file co
a7b0: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20  ntrol opcodes | 
a7c0: 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d  list of opcodes]
a7d0: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69   less than 100 i
a7e0: 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
a7f0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
a800: 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f  t define a custo
a810: 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  m xFileControl m
a820: 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65  ethod should use
a830: 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61   opcodes.** grea
a840: 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20  ter than 100 to 
a850: 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e  avoid conflicts.
a860: 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61    VFS implementa
a870: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20  tions should.** 
a880: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e  return [SQLITE_N
a890: 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c  OTFOUND] for fil
a8a0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
a8b0: 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  s that they do n
a8c0: 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e  ot.** recognize.
a8d0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74  .**.** The xSect
a8e0: 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20  orSize() method 
a8f0: 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74  returns the sect
a900: 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a  or size of the.*
a910: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e  * device that un
a920: 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65  derlies the file
a930: 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69  .  The sector si
a940: 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e  ze is the.** min
a950: 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20  imum write that 
a960: 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64  can be performed
a970: 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62   without disturb
a980: 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74  ing.** other byt
a990: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20  es in the file. 
a9a0: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
a9b0: 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a  acteristics().**
a9c0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
a9d0: 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73  a bit vector des
a9e0: 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72  cribing behavior
a9f0: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65  s of the.** unde
aa00: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a  rlying device:.*
aa10: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
aa20: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
aa30: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20  ATOMIC].** <li> 
aa40: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
aa50: 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC512].** <li>
aa60: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
aa70: 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC1K].** <li>
aa80: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
aa90: 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC2K].** <li>
aaa0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
aab0: 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC4K].** <li>
aac0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
aad0: 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC8K].** <li>
aae0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
aaf0: 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC16K].** <li
ab00: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
ab10: 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC32K].** <l
ab20: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
ab30: 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c  _ATOMIC64K].** <
ab40: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
ab50: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a  P_SAFE_APPEND].*
ab60: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
ab70: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d  OCAP_SEQUENTIAL]
ab80: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
ab90: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
aba0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
abb0: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
abc0: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
abd0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
abe0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
abf0: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
ac00: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
ac10: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
ac20: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
ac30: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
ac40: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
ac50: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
ac60: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
ac70: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
ac80: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
ac90: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
aca0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
acb0: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
acc0: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
acd0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
ace0: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
acf0: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
ad00: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
ad10: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
ad20: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
ad30: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
ad40: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
ad50: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
ad60: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
ad70: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
ad80: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
ad90: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
ada0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
adb0: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
adc0: 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ite()..**.** If 
add0: 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20  xRead() returns 
ade0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f  SQLITE_IOERR_SHO
adf0: 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20  RT_READ it must 
ae00: 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20  also fill.** in 
ae10: 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69  the unread porti
ae20: 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65  ons of the buffe
ae30: 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41  r with zeros.  A
ae40: 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69   VFS that.** fai
ae50: 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  ls to zero-fill 
ae60: 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68  short reads migh
ae70: 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20  t seem to work. 
ae80: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69   However,.** fai
ae90: 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c  lure to zero-fil
aea0: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69  l short reads wi
aeb0: 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65  ll eventually le
aec0: 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73  ad to.** databas
aed0: 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  e corruption..*/
aee0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
aef0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
af00: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ds sqlite3_io_me
af10: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
af20: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
af30: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
af40: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  n;.  int (*xClos
af50: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
af60: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64  );.  int (*xRead
af70: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
af80: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
af90: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
afa0: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
afb0: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f  xWrite)(sqlite3_
afc0: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  file*, const voi
afd0: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
afe0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
aff0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75  t);.  int (*xTru
b000: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66  ncate)(sqlite3_f
b010: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
b020: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74  t64 size);.  int
b030: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
b040: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61  3_file*, int fla
b050: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  gs);.  int (*xFi
b060: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  leSize)(sqlite3_
b070: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
b080: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20  nt64 *pSize);.  
b090: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c  int (*xLock)(sql
b0a0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
b0b0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63  ;.  int (*xUnloc
b0c0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
b0d0: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
b0e0: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
b0f0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
b100: 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  *, int *pResOut)
b110: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43  ;.  int (*xFileC
b120: 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f  ontrol)(sqlite3_
b130: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76  file*, int op, v
b140: 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e  oid *pArg);.  in
b150: 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29  t (*xSectorSize)
b160: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
b170: 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65  .  int (*xDevice
b180: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29  Characteristics)
b190: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
b1a0: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
b1b0: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
b1c0: 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20  r version 1 */. 
b1d0: 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28   int (*xShmMap)(
b1e0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
b1f0: 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a  nt iPg, int pgsz
b200: 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61  , int, void vola
b210: 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  tile**);.  int (
b220: 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74  *xShmLock)(sqlit
b230: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66  e3_file*, int of
b240: 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74  fset, int n, int
b250: 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20   flags);.  void 
b260: 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73  (*xShmBarrier)(s
b270: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
b280: 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70   int (*xShmUnmap
b290: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
b2a0: 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29   int deleteFlag)
b2b0: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
b2c0: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
b2d0: 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a  or version 2 */.
b2e0: 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28    int (*xFetch)(
b2f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
b300: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
b310: 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f  st, int iAmt, vo
b320: 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20  id **pp);.  int 
b330: 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69  (*xUnfetch)(sqli
b340: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
b350: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20  e3_int64 iOfst, 
b360: 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d  void *p);.  /* M
b370: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
b380: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
b390: 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64  on 3 */.  /* Add
b3a0: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20  itional methods 
b3b0: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
b3c0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
b3d0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
b3e0: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20  I3REF: Standard 
b3f0: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63  File Control Opc
b400: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
b410: 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  : {file control 
b420: 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63  opcodes} {file c
b430: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a  ontrol opcode}.*
b440: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
b450: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  er constants are
b460: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65   opcodes for the
b470: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
b480: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  thod.** of the [
b490: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
b4a0: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66  ds] object and f
b4b0: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
b4c0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
b4d0: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
b4e0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
b4f0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  [[SQLITE_FCNTL_L
b500: 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68  OCKSTATE]].** Th
b510: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b520: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
b530: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
b540: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
b550: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
b560: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
b570: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
b580: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
b590: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
b5a0: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
b5b0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
b5c0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
b5d0: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
b5e0: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
b5f0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
b600: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
b610: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
b620: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
b630: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
b640: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
b650: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
b660: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
b670: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
b680: 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76 61   and is only ava
b690: 69 6c 61 62 6c 65 20 77 68 65 6e 20 74 68 65 20  ilable when the 
b6a0: 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63  SQLITE_TEST.** c
b6b0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
b6c0: 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
b6d0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b6e0: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d  CNTL_SIZE_HINT]]
b6f0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
b700: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
b710: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
b720: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76  by SQLite to giv
b730: 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79  e the VFS.** lay
b740: 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77  er a hint of how
b750: 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62   large the datab
b760: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72  ase file will gr
b770: 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20  ow to be during 
b780: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74  the.** current t
b790: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69  ransaction.  Thi
b7a0: 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75  s hint is not gu
b7b0: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61  aranteed to be a
b7c0: 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a  ccurate but it.*
b7d0: 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65  * is often close
b7e0: 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e  .  The underlyin
b7f0: 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f  g VFS might choo
b800: 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74  se to preallocat
b810: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
b820: 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f  le space based o
b830: 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f  n this hint in o
b840: 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69  rder to help wri
b850: 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62  tes to the datab
b860: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20  ase.** file run 
b870: 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  faster..**.** <l
b880: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b890: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a  _CHUNK_SIZE]].**
b8a0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
b8b0: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f  TL_CHUNK_SIZE] o
b8c0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
b8d0: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68   request that th
b8e0: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73  e VFS.** extends
b8f0: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74   and truncates t
b900: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
b910: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20   in chunks of a 
b920: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a  size specified.*
b930: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54  * by the user. T
b940: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
b950: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  nt to [sqlite3_f
b960: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73  ile_control()] s
b970: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20  hould .** point 
b980: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74  to an integer (t
b990: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e  ype int) contain
b9a0: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e  ing the new chun
b9b0: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a  k-size to use.**
b9c0: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74   for the nominat
b9d0: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c  ed database. All
b9e0: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65  ocating database
b9f0: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c   file space in l
ba00: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28  arge.** chunks (
ba10: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d  say 1MB at a tim
ba20: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66  e), may reduce f
ba30: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d  ile-system fragm
ba40: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  entation and.** 
ba50: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
ba60: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74  nce on some syst
ba70: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ems..**.** <li>[
ba80: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
ba90: 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  LE_POINTER]].** 
baa0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
bab0: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20  L_FILE_POINTER] 
bac0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
bad0: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74  o obtain a point
bae0: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  er.** to the [sq
baf0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
bb00: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ct associated wi
bb10: 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  th a particular 
bb20: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
bb30: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73  ection.  See als
bb40: 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  o [SQLITE_FCNTL_
bb50: 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d  JOURNAL_POINTER]
bb60: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
bb70: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e  LITE_FCNTL_JOURN
bb80: 41 4c 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  AL_POINTER]].** 
bb90: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
bba0: 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45  L_JOURNAL_POINTE
bbb0: 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  R] opcode is use
bbc0: 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f  d to obtain a po
bbd0: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
bbe0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
bbf0: 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64  bject associated
bc00: 20 77 69 74 68 20 74 68 65 20 6a 6f 75 72 6e 61   with the journa
bc10: 6c 20 66 69 6c 65 20 28 65 69 74 68 65 72 0a 2a  l file (either.*
bc20: 2a 20 74 68 65 20 5b 72 6f 6c 6c 62 61 63 6b 20  * the [rollback 
bc30: 6a 6f 75 72 6e 61 6c 5d 20 6f 72 20 74 68 65 20  journal] or the 
bc40: 5b 77 72 69 74 65 2d 61 68 65 61 64 20 6c 6f 67  [write-ahead log
bc50: 5d 29 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  ]) for a particu
bc60: 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  lar database.** 
bc70: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65  connection.  See
bc80: 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43   also [SQLITE_FC
bc90: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
bca0: 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  ]..**.** <li>[[S
bcb0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
bcc0: 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f  _OMITTED]].** No
bcd0: 20 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a   longer in use..
bce0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
bcf0: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a  TE_FCNTL_SYNC]].
bd00: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
bd10: 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64  CNTL_SYNC] opcod
bd20: 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69  e is generated i
bd30: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c  nternally by SQL
bd40: 69 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20  ite and.** sent 
bd50: 74 6f 20 74 68 65 20 56 46 53 20 69 6d 6d 65 64  to the VFS immed
bd60: 69 61 74 65 6c 79 20 62 65 66 6f 72 65 20 74 68  iately before th
bd70: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69  e xSync method i
bd80: 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a  s invoked on a.*
bd90: 2a 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  * database file 
bda0: 64 65 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20  descriptor. Or, 
bdb0: 69 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  if the xSync met
bdc0: 68 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  hod is not invok
bdd0: 65 64 20 0a 2a 2a 20 62 65 63 61 75 73 65 20 74  ed .** because t
bde0: 68 65 20 75 73 65 72 20 68 61 73 20 63 6f 6e 66  he user has conf
bdf0: 69 67 75 72 65 64 20 53 51 4c 69 74 65 20 77 69  igured SQLite wi
be00: 74 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73  th .** [PRAGMA s
be10: 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41  ynchronous | PRA
be20: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d  GMA synchronous=
be30: 4f 46 46 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b  OFF] it is invok
be40: 65 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20  ed in place .** 
be50: 6f 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  of the xSync met
be60: 68 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73  hod. In most cas
be70: 65 73 2c 20 74 68 65 20 70 6f 69 6e 74 65 72 20  es, the pointer 
be80: 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
be90: 77 69 74 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c  with.** this fil
bea0: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c  e-control is NUL
beb0: 4c 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74  L. However, if t
bec0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
bed0: 20 69 73 20 62 65 69 6e 67 20 73 79 6e 63 65 64   is being synced
bee0: 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 61  .** as part of a
bef0: 20 6d 75 6c 74 69 2d 64 61 74 61 62 61 73 65 20   multi-database 
bf00: 63 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72 67 75  commit, the argu
bf10: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61  ment points to a
bf20: 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a   nul-terminated.
bf30: 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  ** string contai
bf40: 6e 69 6e 67 20 74 68 65 20 74 72 61 6e 73 61 63  ning the transac
bf50: 74 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75  tions master-jou
bf60: 72 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20  rnal file name. 
bf70: 56 46 53 65 73 20 74 68 61 74 20 0a 2a 2a 20 64  VFSes that .** d
bf80: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20  o not need this 
bf90: 73 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69  signal should si
bfa0: 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68  lently ignore th
bfb0: 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69  is opcode. Appli
bfc0: 63 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75  cations .** shou
bfd0: 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c  ld not call [sql
bfe0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
bff0: 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f  l()] with this o
c000: 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73  pcode as doing s
c010: 6f 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75 70  o may .** disrup
c020: 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  t the operation 
c030: 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a  of the specializ
c040: 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f  ed VFSes that do
c050: 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a   require it.  .*
c060: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
c070: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50  E_FCNTL_COMMIT_P
c080: 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65  HASETWO]].** The
c090: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43   [SQLITE_FCNTL_C
c0a0: 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 20  OMMIT_PHASETWO] 
c0b0: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61  opcode is genera
c0c0: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  ted internally b
c0d0: 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  y SQLite.** and 
c0e0: 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20  sent to the VFS 
c0f0: 61 66 74 65 72 20 61 20 74 72 61 6e 73 61 63 74  after a transact
c100: 69 6f 6e 20 68 61 73 20 62 65 65 6e 20 63 6f 6d  ion has been com
c110: 6d 69 74 74 65 64 20 69 6d 6d 65 64 69 61 74 65  mitted immediate
c120: 6c 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72 65  ly.** but before
c130: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
c140: 20 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73   unlocked. VFSes
c150: 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65   that do not nee
c160: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a  d this signal.**
c170: 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79   should silently
c180: 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63   ignore this opc
c190: 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e  ode. Application
c1a0: 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c  s should not cal
c1b0: 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  l.** [sqlite3_fi
c1c0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69  le_control()] wi
c1d0: 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61  th this opcode a
c1e0: 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64  s doing so may d
c1f0: 69 73 72 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f  isrupt the .** o
c200: 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  peration of the 
c210: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65  specialized VFSe
c220: 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72  s that do requir
c230: 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c  e it.  .**.** <l
c240: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
c250: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d  _WIN32_AV_RETRY]
c260: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
c270: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
c280: 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69  _RETRY] opcode i
c290: 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67  s used to config
c2a0: 75 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a  ure automatic.**
c2b0: 20 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e   retry counts an
c2c0: 64 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20  d intervals for 
c2d0: 63 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f  certain disk I/O
c2e0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20   operations for 
c2f0: 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b  the.** windows [
c300: 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  VFS] in order to
c310: 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e   provide robustn
c320: 65 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65  ess in the prese
c330: 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76  nce of.** anti-v
c340: 69 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20  irus programs.  
c350: 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20  By default, the 
c360: 77 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c  windows VFS will
c370: 20 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64   retry file read
c380: 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c  ,.** file write,
c390: 20 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65   and file delete
c3a0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74   operations up t
c3b0: 6f 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68  o 10 times, with
c3c0: 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32   a delay.** of 2
c3d0: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62  5 milliseconds b
c3e0: 65 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20  efore the first 
c3f0: 72 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74  retry and with t
c400: 68 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73  he delay increas
c410: 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64  ing.** by an add
c420: 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69  itional 25 milli
c430: 73 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63  seconds with eac
c440: 68 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74  h subsequent ret
c450: 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63  ry.  This.** opc
c460: 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65  ode allows these
c470: 20 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20   two values (10 
c480: 72 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d  retries and 25 m
c490: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64  illiseconds of d
c4a0: 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61  elay).** to be a
c4b0: 64 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61  djusted.  The va
c4c0: 6c 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64  lues are changed
c4d0: 20 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73   for all databas
c4e0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
c4f0: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
c500: 20 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61   process.  The a
c510: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
c520: 6e 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79  nter to an array
c530: 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67   of two.** integ
c540: 65 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69  ers where the fi
c550: 72 73 74 20 69 6e 74 65 67 65 72 20 69 20 74 68  rst integer i th
c560: 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e  e new retry coun
c570: 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
c580: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74  .** integer is t
c590: 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69  he delay.  If ei
c5a0: 74 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20  ther integer is 
c5b0: 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
c5c0: 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73  he setting.** is
c5d0: 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74   not changed but
c5e0: 20 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69   instead the pri
c5f0: 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74  or value of that
c600: 20 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74   setting is writ
c610: 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ten.** into the 
c620: 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c  array entry, all
c630: 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e  owing the curren
c640: 74 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73  t retry settings
c650: 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72   to be.** interr
c660: 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62  ogated.  The zDb
c670: 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  Name parameter i
c680: 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  s ignored..**.**
c690: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
c6a0: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d  NTL_PERSIST_WAL]
c6b0: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
c6c0: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
c6d0: 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  WAL] opcode is u
c6e0: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75  sed to set or qu
c6f0: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69  ery the.** persi
c700: 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69  stent [WAL | Wri
c710: 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65  te Ahead Log] se
c720: 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75  tting.  By defau
c730: 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72  lt, the auxiliar
c740: 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64  y.** write ahead
c750: 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20   log and shared 
c760: 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65  memory files use
c770: 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f  d for transactio
c780: 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65  n control.** are
c790: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
c7a0: 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20  eleted when the 
c7b0: 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f  latest connectio
c7c0: 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  n to the databas
c7d0: 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65  e.** closes.  Se
c7e0: 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74  tting persistent
c7f0: 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73   WAL mode causes
c800: 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20   those files to 
c810: 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a  persist after.**
c820: 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74   close.  Persist
c830: 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73  ing the files is
c840: 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68   useful when oth
c850: 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61  er processes tha
c860: 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65  t do not.** have
c870: 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f   write permissio
c880: 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f  n on the directo
c890: 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ry containing th
c8a0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
c8b0: 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20  want.** to read 
c8c0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
c8d0: 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e  e, as the WAL an
c8e0: 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20  d shared memory 
c8f0: 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74  files must exist
c900: 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72  .** in order for
c910: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f   the database to
c920: 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54   be readable.  T
c930: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
c940: 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
c950: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
c960: 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f  )] for this opco
c970: 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70  de should be a p
c980: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
c990: 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e  eger..** That in
c9a0: 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69  teger is 0 to di
c9b0: 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74  sable persistent
c9c0: 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74   WAL mode or 1 t
c9d0: 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74  o enable persist
c9e0: 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e  ent.** WAL mode.
c9f0: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72    If the integer
ca00: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20   is -1, then it 
ca10: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
ca20: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ith the current.
ca30: 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e  ** WAL persisten
ca40: 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a  ce setting..**.*
ca50: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
ca60: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
ca70: 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54  VERWRITE]].** ^T
ca80: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
ca90: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
caa0: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  RITE] opcode is 
cab0: 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71  used to set or q
cac0: 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73  uery the.** pers
cad0: 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66  istent "powersaf
cae0: 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20  e-overwrite" or 
caf0: 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20  "PSOW" setting. 
cb00: 20 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e   The PSOW settin
cb10: 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20  g.** determines 
cb20: 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  the [SQLITE_IOCA
cb30: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
cb40: 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68  WRITE] bit of th
cb50: 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72  e.** xDeviceChar
cb60: 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68  acteristics meth
cb70: 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20  ods. The fourth 
cb80: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
cb90: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
cba0: 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69  ntrol()] for thi
cbb0: 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20  s opcode should 
cbc0: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
cbd0: 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54  an integer..** T
cbe0: 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30  hat integer is 0
cbf0: 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f   to disable zero
cc00: 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20  -damage mode or 
cc10: 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f  1 to enable zero
cc20: 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e  -damage.** mode.
cc30: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72    If the integer
cc40: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20   is -1, then it 
cc50: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
cc60: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ith the current.
cc70: 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d  ** zero-damage m
cc80: 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a  ode setting..**.
cc90: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
cca0: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d  FCNTL_OVERWRITE]
ccb0: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
ccc0: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54  E_FCNTL_OVERWRIT
ccd0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76  E] opcode is inv
cce0: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  oked by SQLite a
ccf0: 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20  fter opening.** 
cd00: 61 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 74  a write transact
cd10: 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20  ion to indicate 
cd20: 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20  that, unless it 
cd30: 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66  is rolled back f
cd40: 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f  or some.** reaso
cd50: 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64 61  n, the entire da
cd60: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
cd70: 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20   be overwritten 
cd80: 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a  by the current .
cd90: 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20  ** transaction. 
cda0: 54 68 69 73 20 69 73 20 75 73 65 64 20 62 79 20  This is used by 
cdb0: 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e  VACUUM operation
cdc0: 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  s..**.** <li>[[S
cdd0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
cde0: 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  AME]].** ^The [S
cdf0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
ce00: 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20  AME] opcode can 
ce10: 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
ce20: 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a  n the names of.*
ce30: 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e  * all [VFSes] in
ce40: 20 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20   the VFS stack. 
ce50: 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f   The names are o
ce60: 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20  f all VFS shims 
ce70: 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c  and the.** final
ce80: 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46   bottom-level VF
ce90: 53 20 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e  S are written in
cea0: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
ceb0: 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c  ed from .** [sql
cec0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61  ite3_malloc()] a
ced0: 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  nd the result is
cee0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63   stored in the c
cef0: 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a  har* variable.**
cf00: 20 74 68 61 74 20 74 68 65 20 66 6f 75 72 74 68   that the fourth
cf10: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73   parameter of [s
cf20: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
cf30: 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f  rol()] points to
cf40: 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20  ..** The caller 
cf50: 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
cf60: 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d  or freeing the m
cf70: 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e  emory when done.
cf80: 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c    As with.** all
cf90: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63   file-control ac
cfa0: 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20  tions, there is 
cfb0: 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  no guarantee tha
cfc0: 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75  t this will actu
cfd0: 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68  ally.** do anyth
cfe0: 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68  ing.  Callers sh
cff0: 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20  ould initialize 
d000: 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62  the char* variab
d010: 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20  le to a NULL.** 
d020: 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20  pointer in case 
d030: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
d040: 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65  l is not impleme
d050: 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65  nted.  This file
d060: 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69  -control.** is i
d070: 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67  ntended for diag
d080: 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e  nostic use only.
d090: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
d0a0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f  ITE_FCNTL_VFS_PO
d0b0: 49 4e 54 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20  INTER]].** ^The 
d0c0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  [SQLITE_FCNTL_VF
d0d0: 53 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  S_POINTER] opcod
d0e0: 65 20 66 69 6e 64 73 20 61 20 70 6f 69 6e 74 65  e finds a pointe
d0f0: 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76  r to the top-lev
d100: 65 6c 0a 2a 2a 20 5b 56 46 53 65 73 5d 20 63 75  el.** [VFSes] cu
d110: 72 72 65 6e 74 6c 79 20 69 6e 20 75 73 65 2e 20  rrently in use. 
d120: 20 5e 28 54 68 65 20 61 72 67 75 6d 65 6e 74 20   ^(The argument 
d130: 58 20 69 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  X in.** sqlite3_
d140: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 64 62 2c  file_control(db,
d150: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
d160: 5f 50 4f 49 4e 54 45 52 2c 58 29 20 6d 75 73 74  _POINTER,X) must
d170: 20 62 65 0a 2a 2a 20 6f 66 20 74 79 70 65 20 22   be.** of type "
d180: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 2a 2a  [sqlite3_vfs] **
d190: 22 2e 20 20 54 68 69 73 20 6f 70 63 6f 64 65 73  ".  This opcodes
d1a0: 20 77 69 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a 20   will set *X.** 
d1b0: 74 6f 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  to a pointer to 
d1c0: 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 20 56 46  the top-level VF
d1d0: 53 2e 29 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68  S.)^.** ^When th
d1e0: 65 72 65 20 61 72 65 20 6d 75 6c 74 69 70 6c 65  ere are multiple
d1f0: 20 56 46 53 20 73 68 69 6d 73 20 69 6e 20 74 68   VFS shims in th
d200: 65 20 73 74 61 63 6b 2c 20 74 68 69 73 20 6f 70  e stack, this op
d210: 63 6f 64 65 20 66 69 6e 64 73 20 74 68 65 0a 2a  code finds the.*
d220: 2a 20 75 70 70 65 72 2d 6d 6f 73 74 20 73 68 69  * upper-most shi
d230: 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  m only..**.** <l
d240: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
d250: 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68  _PRAGMA]].** ^Wh
d260: 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41  enever a [PRAGMA
d270: 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70  ] statement is p
d280: 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54  arsed, an [SQLIT
d290: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
d2a0: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
d2b0: 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20   is sent to the 
d2c0: 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  open [sqlite3_fi
d2d0: 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65  le] object corre
d2e0: 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74  sponding.** to t
d2f0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
d300: 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 70 72   to which the pr
d310: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72  agma statement r
d320: 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75  efers. ^The argu
d330: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ment.** to the [
d340: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
d350: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
d360: 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  l is an array of
d370: 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
d380: 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29  strings (char**)
d390: 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 73 65   in which the se
d3a0: 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20  cond element of 
d3b0: 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20  the array.** is 
d3c0: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
d3d0: 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74  pragma and the t
d3e0: 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20  hird element is 
d3f0: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  the argument to 
d400: 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72  the.** pragma or
d410: 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61   NULL if the pra
d420: 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d  gma has no argum
d430: 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c  ent.  ^The handl
d440: 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51  er for an.** [SQ
d450: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
d460: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
d470: 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d  can optionally m
d480: 61 6b 65 20 74 68 65 20 66 69 72 73 74 20 65 6c  ake the first el
d490: 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20  ement.** of the 
d4a0: 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20  char** argument 
d4b0: 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
d4c0: 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  g obtained from 
d4d0: 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  [sqlite3_mprintf
d4e0: 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71  ()].** or the eq
d4f0: 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61  uivalent and tha
d500: 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  t string will be
d510: 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20  come the result 
d520: 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72  of the pragma or
d530: 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65  .** the error me
d540: 73 73 61 67 65 20 69 66 20 74 68 65 20 70 72 61  ssage if the pra
d550: 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74  gma fails. ^If t
d560: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  he.** [SQLITE_FC
d570: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
d580: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
d590: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
d5a0: 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20  D], then normal 
d5b0: 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f  .** [PRAGMA] pro
d5c0: 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65  cessing continue
d5d0: 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  s.  ^If the [SQL
d5e0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
d5f0: 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f  ].** file contro
d600: 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  l returns [SQLIT
d610: 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20  E_OK], then the 
d620: 70 61 72 73 65 72 20 61 73 73 75 6d 65 73 20 74  parser assumes t
d630: 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68  hat the.** VFS h
d640: 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50  as handled the P
d650: 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64  RAGMA itself and
d660: 20 74 68 65 20 70 61 72 73 65 72 20 67 65 6e 65   the parser gene
d670: 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a  rates a no-op.**
d680: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
d690: 65 6e 74 20 69 66 20 72 65 73 75 6c 74 20 73 74  ent if result st
d6a0: 72 69 6e 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72  ring is NULL, or
d6b0: 20 74 68 61 74 20 72 65 74 75 72 6e 73 20 61 20   that returns a 
d6c0: 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72  copy.** of the r
d6d0: 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 66 20  esult string if 
d6e0: 74 68 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  the string is no
d6f0: 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74  n-NULL..** ^If t
d700: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
d710: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
d720: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a  ntrol returns.**
d730: 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 65   any result code
d740: 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
d750: 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49  ITE_OK] or [SQLI
d760: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68  TE_NOTFOUND], th
d770: 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  at means.** that
d780: 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e 74   the VFS encount
d790: 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77 68  ered an error wh
d7a0: 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 65  ile handling the
d7b0: 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 68   [PRAGMA] and th
d7c0: 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e  e.** compilation
d7d0: 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20 66   of the PRAGMA f
d7e0: 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72 72  ails with an err
d7f0: 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  or.  ^The [SQLIT
d800: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a  E_FCNTL_PRAGMA].
d810: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
d820: 6f 63 63 75 72 73 20 61 74 20 74 68 65 20 62 65  occurs at the be
d830: 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d  ginning of pragm
d840: 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c  a statement anal
d850: 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69  ysis and so.** i
d860: 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 65  t is able to ove
d870: 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b  rride built-in [
d880: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e  PRAGMA] statemen
d890: 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ts..**.** <li>[[
d8a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
d8b0: 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54  YHANDLER]].** ^T
d8c0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
d8d0: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a  _BUSYHANDLER].**
d8e0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61   file-control ma
d8f0: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 20  y be invoked by 
d900: 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64 61  SQLite on the da
d910: 74 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e 64  tabase file hand
d920: 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66  le.** shortly af
d930: 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65 64  ter it is opened
d940: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f   in order to pro
d950: 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56 46  vide a custom VF
d960: 53 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a 2a  S with access.**
d970: 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74 69   to the connecti
d980: 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65 72  ons busy-handler
d990: 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61   callback. The a
d9a0: 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74 79  rgument is of ty
d9b0: 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20  pe (void **).** 
d9c0: 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77  - an array of tw
d9d0: 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75 65  o (void *) value
d9e0: 73 2e 20 54 68 65 20 66 69 72 73 74 20 28 76 6f  s. The first (vo
d9f0: 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20 70  id *) actually p
da00: 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75  oints.** to a fu
da10: 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 28  nction of type (
da20: 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29 29  int (*)(void *))
da30: 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  . In order to in
da40: 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63 74  voke the connect
da50: 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e  ions.** busy-han
da60: 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63 74  dler, this funct
da70: 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 6e  ion should be in
da80: 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20 73  voked with the s
da90: 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20 69  econd (void *) i
daa0: 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20 61  n.** the array a
dab0: 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d  s the only argum
dac0: 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75 72  ent. If it retur
dad0: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
dae0: 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  n the operation.
daf0: 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
db00: 72 69 65 64 2e 20 49 66 20 69 74 20 72 65 74 75  ried. If it retu
db10: 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63 75  rns zero, the cu
db20: 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64 20  stom VFS should 
db30: 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63  abandon the.** c
db40: 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e  urrent operation
db50: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
db60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
db70: 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70  ILENAME]].** ^Ap
db80: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e  plication can in
db90: 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49 54 45  voke the [SQLITE
dba0: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e  _FCNTL_TEMPFILEN
dbb0: 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  AME] file-contro
dbc0: 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53 51 4c  l.** to have SQL
dbd0: 69 74 65 20 67 65 6e 65 72 61 74 65 20 61 0a 2a  ite generate a.*
dbe0: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
dbf0: 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65 20 73  name using the s
dc00: 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 74 68  ame algorithm th
dc10: 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74  at is followed t
dc20: 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65  o generate.** te
dc30: 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65  mporary filename
dc40: 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62 6c 65  s for TEMP table
dc50: 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e 74 65  s and other inte
dc60: 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 65 0a  rnal uses.  The.
dc70: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
dc80: 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a 20 77  ld be a char** w
dc90: 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66 69 6c  hich will be fil
dca0: 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 69 6c  led with the fil
dcb0: 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e  ename.** written
dcc0: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
dcd0: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
dce0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20  te3_malloc()].  
dcf0: 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c  The caller shoul
dd00: 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  d.** invoke [sql
dd10: 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20  ite3_free()] on 
dd20: 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20 61 76  the result to av
dd30: 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61  oid a memory lea
dd40: 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  k..**.** <li>[[S
dd50: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50  QLITE_FCNTL_MMAP
dd60: 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _SIZE]].** The [
dd70: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
dd80: 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e  P_SIZE] file con
dd90: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 74 6f 20  trol is used to 
dda0: 71 75 65 72 79 20 6f 72 20 73 65 74 20 74 68 65  query or set the
ddb0: 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  .** maximum numb
ddc0: 65 72 20 6f 66 20 62 79 74 65 73 20 74 68 61 74  er of bytes that
ddd0: 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 66 6f   will be used fo
dde0: 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20  r memory-mapped 
ddf0: 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75  I/O..** The argu
de00: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
de10: 72 20 74 6f 20 61 20 76 61 6c 75 65 20 6f 66 20  r to a value of 
de20: 74 79 70 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  type sqlite3_int
de30: 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e  64 that.** is an
de40: 20 61 64 76 69 73 6f 72 79 20 6d 61 78 69 6d 75   advisory maximu
de50: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  m number of byte
de60: 73 20 69 6e 20 74 68 65 20 66 69 6c 65 20 74 6f  s in the file to
de70: 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68   memory map.  Th
de80: 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 20  e.** pointer is 
de90: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
dea0: 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20   the old value. 
deb0: 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f   The limit is no
dec0: 74 20 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20  t changed if.** 
ded0: 74 68 65 20 76 61 6c 75 65 20 6f 72 69 67 69 6e  the value origin
dee0: 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f 20  ally pointed to 
def0: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61 6e 64  is negative, and
df00: 20 73 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   so the current 
df10: 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65  limit .** can be
df20: 20 71 75 65 72 69 65 64 20 62 79 20 70 61 73 73   queried by pass
df30: 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74 65 72  ing in a pointer
df40: 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65 20 6e   to a negative n
df50: 75 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20  umber.  This.** 
df60: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20  file-control is 
df70: 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
df80: 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52  to implement [PR
df90: 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e  AGMA mmap_size].
dfa0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
dfb0: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  ITE_FCNTL_TRACE]
dfc0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
dfd0: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69  _FCNTL_TRACE] fi
dfe0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69  le control provi
dff0: 64 65 73 20 61 64 76 69 73 6f 72 79 20 69 6e 66  des advisory inf
e000: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74  ormation.** to t
e010: 68 65 20 56 46 53 20 61 62 6f 75 74 20 77 68 61  he VFS about wha
e020: 74 20 74 68 65 20 68 69 67 68 65 72 20 6c 61 79  t the higher lay
e030: 65 72 73 20 6f 66 20 74 68 65 20 53 51 4c 69 74  ers of the SQLit
e040: 65 20 73 74 61 63 6b 20 61 72 65 20 64 6f 69 6e  e stack are doin
e050: 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20  g..** This file 
e060: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20  control is used 
e070: 62 79 20 73 6f 6d 65 20 56 46 53 20 61 63 74 69  by some VFS acti
e080: 76 69 74 79 20 74 72 61 63 69 6e 67 20 5b 73 68  vity tracing [sh
e090: 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67  ims]..** The arg
e0a0: 75 6d 65 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d  ument is a zero-
e0b0: 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
e0c0: 67 2e 20 20 48 69 67 68 65 72 20 6c 61 79 65 72  g.  Higher layer
e0d0: 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69  s in the.** SQLi
e0e0: 74 65 20 73 74 61 63 6b 20 6d 61 79 20 67 65 6e  te stack may gen
e0f0: 65 72 61 74 65 20 69 6e 73 74 61 6e 63 65 73 20  erate instances 
e100: 6f 66 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e  of this file con
e110: 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b  trol if.** the [
e120: 53 51 4c 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c  SQLITE_USE_FCNTL
e130: 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d  _TRACE] compile-
e140: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65  time option is e
e150: 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  nabled..**.** <l
e160: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
e170: 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20  _HAS_MOVED]].** 
e180: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
e190: 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c  L_HAS_MOVED] fil
e1a0: 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70  e control interp
e1b0: 72 65 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e  rets its argumen
e1c0: 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  t as a.** pointe
e1d0: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
e1e0: 61 6e 64 20 69 74 20 77 72 69 74 65 73 20 61 20  and it writes a 
e1f0: 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61  boolean into tha
e200: 74 20 69 6e 74 65 67 65 72 20 64 65 70 65 6e 64  t integer depend
e210: 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  ing.** on whethe
e220: 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 66 69 6c  r or not the fil
e230: 65 20 68 61 73 20 62 65 65 6e 20 72 65 6e 61 6d  e has been renam
e240: 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65  ed, moved, or de
e250: 6c 65 74 65 64 20 73 69 6e 63 65 20 69 74 0a 2a  leted since it.*
e260: 2a 20 77 61 73 20 66 69 72 73 74 20 6f 70 65 6e  * was first open
e270: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
e280: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
e290: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a  32_SET_HANDLE]].
e2a0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
e2b0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48  CNTL_WIN32_SET_H
e2c0: 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73  ANDLE] opcode is
e2d0: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67   used for debugg
e2e0: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  ing.  This.** op
e2f0: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20  code causes the 
e300: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
e310: 68 6f 64 20 74 6f 20 73 77 61 70 20 74 68 65 20  hod to swap the 
e320: 66 69 6c 65 20 68 61 6e 64 6c 65 20 77 69 74 68  file handle with
e330: 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e   the one.** poin
e340: 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 70 41  ted to by the pA
e350: 72 67 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68  rg argument.  Th
e360: 69 73 20 63 61 70 61 62 69 6c 69 74 79 20 69 73  is capability is
e370: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
e380: 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79  ting.** and only
e390: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70   needs to be sup
e3a0: 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49  ported when SQLI
e3b0: 54 45 5f 54 45 53 54 20 69 73 20 64 65 66 69 6e  TE_TEST is defin
e3c0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
e3d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c  SQLITE_FCNTL_WAL
e3e0: 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20  _BLOCK]].** The 
e3f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41  [SQLITE_FCNTL_WA
e400: 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69  L_BLOCK] is a si
e410: 67 6e 61 6c 20 74 6f 20 74 68 65 20 56 46 53 20  gnal to the VFS 
e420: 6c 61 79 65 72 20 74 68 61 74 20 69 74 20 6d 69  layer that it mi
e430: 67 68 74 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74  ght.** be advant
e440: 61 67 65 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20  ageous to block 
e450: 6f 6e 20 74 68 65 20 6e 65 78 74 20 57 41 4c 20  on the next WAL 
e460: 6c 6f 63 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b  lock if the lock
e470: 20 69 73 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74   is not immediat
e480: 65 6c 79 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65  ely.** available
e490: 2e 20 20 54 68 65 20 57 41 4c 20 73 75 62 73 79  .  The WAL subsy
e4a0: 73 74 65 6d 20 69 73 73 75 65 73 20 74 68 69 73  stem issues this
e4b0: 20 73 69 67 6e 61 6c 20 64 75 72 69 6e 67 20 72   signal during r
e4c0: 61 72 65 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61  are.** circumsta
e4d0: 6e 63 65 73 20 69 6e 20 6f 72 64 65 72 20 74 6f  nces in order to
e4e0: 20 66 69 78 20 61 20 70 72 6f 62 6c 65 6d 20 77   fix a problem w
e4f0: 69 74 68 20 70 72 69 6f 72 69 74 79 20 69 6e 76  ith priority inv
e500: 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69  ersion..** Appli
e510: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c  cations should <
e520: 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20  em>not</em> use 
e530: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
e540: 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  l..**.** <li>[[S
e550: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56  QLITE_FCNTL_ZIPV
e560: 46 53 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  FS]].** The [SQL
e570: 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53  ITE_FCNTL_ZIPVFS
e580: 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c  ] opcode is impl
e590: 65 6d 65 6e 74 65 64 20 62 79 20 7a 69 70 76 66  emented by zipvf
e5a0: 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65  s only. All othe
e5b0: 72 0a 2a 2a 20 56 46 53 20 73 68 6f 75 6c 64 20  r.** VFS should 
e5c0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f  return SQLITE_NO
e5d0: 54 46 4f 55 4e 44 20 66 6f 72 20 74 68 69 73 20  TFOUND for this 
e5e0: 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  opcode..**.** <l
e5f0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
e600: 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  _RBU]].** The [S
e610: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d  QLITE_FCNTL_RBU]
e620: 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65   opcode is imple
e630: 6d 65 6e 74 65 64 20 62 79 20 74 68 65 20 73 70  mented by the sp
e640: 65 63 69 61 6c 20 56 46 53 20 75 73 65 64 20 62  ecial VFS used b
e650: 79 0a 2a 2a 20 74 68 65 20 52 42 55 20 65 78 74  y.** the RBU ext
e660: 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c  ension only.  Al
e670: 6c 20 6f 74 68 65 72 20 56 46 53 20 73 68 6f 75  l other VFS shou
e680: 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ld return SQLITE
e690: 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a  _NOTFOUND for.**
e6a0: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a   this opcode.  .
e6b0: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </ul>.*/.#def
e6c0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
e6d0: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20  _LOCKSTATE      
e6e0: 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
e6f0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
e700: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
e710: 45 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e  E       2.#defin
e720: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
e730: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
e740: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
e750: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41   SQLITE_FCNTL_LA
e760: 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20  ST_ERRNO        
e770: 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
e780: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
e790: 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20 20  E_HINT          
e7a0: 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
e7b0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
e7c0: 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20  K_SIZE          
e7d0: 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51      6.#define SQ
e7e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
e7f0: 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20  POINTER         
e800: 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c     7.#define SQL
e810: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f  ITE_FCNTL_SYNC_O
e820: 4d 49 54 54 45 44 20 20 20 20 20 20 20 20 20 20  MITTED          
e830: 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
e840: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
e850: 56 5f 52 45 54 52 59 20 20 20 20 20 20 20 20 20  V_RETRY         
e860: 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
e870: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
e880: 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 31  WAL            1
e890: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
e8a0: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
e8b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 31                11
e8c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e8d0: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20  FCNTL_VFSNAME   
e8e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 32 0a               12.
e8f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
e900: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
e910: 56 45 52 57 52 49 54 45 20 20 20 20 31 33 0a 23  VERWRITE    13.#
e920: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
e930: 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20  NTL_PRAGMA      
e940: 20 20 20 20 20 20 20 20 20 20 20 31 34 0a 23 64             14.#d
e950: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
e960: 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20  TL_BUSYHANDLER  
e970: 20 20 20 20 20 20 20 20 20 20 31 35 0a 23 64 65            15.#de
e980: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
e990: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20  L_TEMPFILENAME  
e9a0: 20 20 20 20 20 20 20 20 20 31 36 0a 23 64 65 66           16.#def
e9b0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
e9c0: 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20  _MMAP_SIZE      
e9d0: 20 20 20 20 20 20 20 20 31 38 0a 23 64 65 66 69          18.#defi
e9e0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
e9f0: 54 52 41 43 45 20 20 20 20 20 20 20 20 20 20 20  TRACE           
ea00: 20 20 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e         19.#defin
ea10: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48  e SQLITE_FCNTL_H
ea20: 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20  AS_MOVED        
ea30: 20 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65        20.#define
ea40: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59   SQLITE_FCNTL_SY
ea50: 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NC              
ea60: 20 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20       21.#define 
ea70: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
ea80: 4d 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20  MIT_PHASETWO    
ea90: 20 20 20 20 32 32 0a 23 64 65 66 69 6e 65 20 53      22.#define S
eaa0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
eab0: 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20 20 20  2_SET_HANDLE    
eac0: 20 20 20 32 33 0a 23 64 65 66 69 6e 65 20 53 51     23.#define SQ
ead0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42  LITE_FCNTL_WAL_B
eae0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
eaf0: 20 20 32 34 0a 23 64 65 66 69 6e 65 20 53 51 4c    24.#define SQL
eb00: 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53  ITE_FCNTL_ZIPVFS
eb10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
eb20: 20 32 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   25.#define SQLI
eb30: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 20 20 20 20  TE_FCNTL_RBU    
eb40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
eb50: 32 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  26.#define SQLIT
eb60: 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e  E_FCNTL_VFS_POIN
eb70: 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20 32  TER            2
eb80: 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
eb90: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50  _FCNTL_JOURNAL_P
eba0: 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 32 38  OINTER        28
ebb0: 0a 0a 2f 2a 20 64 65 70 72 65 63 61 74 65 64 20  ../* deprecated 
ebc0: 6e 61 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  names */.#define
ebd0: 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b   SQLITE_GET_LOCK
ebe0: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53  PROXYFILE      S
ebf0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f  QLITE_FCNTL_GET_
ec00: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64  LOCKPROXYFILE.#d
ec10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54  efine SQLITE_SET
ec20: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
ec30: 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c      SQLITE_FCNTL
ec40: 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _SET_LOCKPROXYFI
ec50: 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  LE.#define SQLIT
ec60: 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20  E_LAST_ERRNO    
ec70: 20 20 20 20 20 20 20 20 20 53 51 4c 49 54 45 5f           SQLITE_
ec80: 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f  FCNTL_LAST_ERRNO
ec90: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
eca0: 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a  F: Mutex Handle.
ecb0: 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20  **.** The mutex 
ecc0: 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51  module within SQ
ecd0: 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71  Lite defines [sq
ece0: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20  lite3_mutex] to 
ecf0: 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63  be an.** abstrac
ed00: 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74  t type for a mut
ed10: 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20  ex object.  The 
ed20: 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65  SQLite core neve
ed30: 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68  r looks.** at th
ed40: 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
ed50: 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  sentation of an 
ed60: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e  [sqlite3_mutex].
ed70: 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61    It only.** dea
ed80: 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73  ls with pointers
ed90: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
eda0: 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a  _mutex] object..
edb0: 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72  **.** Mutexes ar
edc0: 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  e created using 
edd0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  [sqlite3_mutex_a
ede0: 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  lloc()]..*/.type
edf0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
ee00: 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33  e3_mutex sqlite3
ee10: 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _mutex;../*.** C
ee20: 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 61 62 6c  API3REF: Loadabl
ee30: 65 20 45 78 74 65 6e 73 69 6f 6e 20 54 68 75 6e  e Extension Thun
ee40: 6b 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65  k.**.** A pointe
ee50: 72 20 74 6f 20 74 68 65 20 6f 70 61 71 75 65 20  r to the opaque 
ee60: 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74  sqlite3_api_rout
ee70: 69 6e 65 73 20 73 74 72 75 63 74 75 72 65 20 69  ines structure i
ee80: 73 20 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74  s passed as.** t
ee90: 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
eea0: 65 72 20 74 6f 20 65 6e 74 72 79 20 70 6f 69 6e  er to entry poin
eeb0: 74 73 20 6f 66 20 5b 6c 6f 61 64 61 62 6c 65 20  ts of [loadable 
eec0: 65 78 74 65 6e 73 69 6f 6e 73 5d 2e 20 20 54 68  extensions].  Th
eed0: 69 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  is.** structure 
eee0: 6d 75 73 74 20 62 65 20 74 79 70 65 64 65 66 65  must be typedefe
eef0: 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 77 6f  d in order to wo
ef00: 72 6b 20 61 72 6f 75 6e 64 20 63 6f 6d 70 69 6c  rk around compil
ef10: 65 72 20 77 61 72 6e 69 6e 67 73 0a 2a 2a 20 6f  er warnings.** o
ef20: 6e 20 73 6f 6d 65 20 70 6c 61 74 66 6f 72 6d 73  n some platforms
ef30: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
ef40: 75 63 74 20 73 71 6c 69 74 65 33 5f 61 70 69 5f  uct sqlite3_api_
ef50: 72 6f 75 74 69 6e 65 73 20 73 71 6c 69 74 65 33  routines sqlite3
ef60: 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 3b 0a 0a  _api_routines;..
ef70: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
ef80: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a  OS Interface Obj
ef90: 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ect.**.** An ins
efa0: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c  tance of the sql
efb0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
efc0: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
efd0: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a  rface between.**
efe0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
eff0: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79   and the underly
f000: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
f010: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22  stem.  The "vfs"
f020: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  .** in the name 
f030: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74  of the object st
f040: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61  ands for "virtua
f050: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20  l file system". 
f060: 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53   See.** the [VFS
f070: 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61   | VFS documenta
f080: 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65  tion] for furthe
f090: 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  r information..*
f0a0: 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f  *.** The value o
f0b0: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  f the iVersion f
f0c0: 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c  ield is initiall
f0d0: 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c  y 1 but may be l
f0e0: 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75  arger in.** futu
f0f0: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
f100: 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e  QLite.  Addition
f110: 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65  al fields may be
f120: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69   appended to thi
f130: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e  s.** object when
f140: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61   the iVersion va
f150: 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64  lue is increased
f160: 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  .  Note that the
f170: 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66   structure.** of
f180: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
f190: 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20   object changes 
f1a0: 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  in the transacti
f1b0: 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51  on between.** SQ
f1c0: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
f1d0: 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64  .9 and 3.6.0 and
f1e0: 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f   yet the iVersio
f1f0: 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a  n field was not.
f200: 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a  ** modified..**.
f210: 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20  ** The szOsFile 
f220: 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a  field is the siz
f230: 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73  e of the subclas
f240: 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  sed [sqlite3_fil
f250: 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  e].** structure 
f260: 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53  used by this VFS
f270: 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73  .  mxPathname is
f280: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e   the maximum len
f290: 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68  gth of.** a path
f2a0: 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53  name in this VFS
f2b0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72  ..**.** Register
f2c0: 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  ed sqlite3_vfs o
f2d0: 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20  bjects are kept 
f2e0: 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74  on a linked list
f2f0: 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68   formed by.** th
f300: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
f310: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
f320: 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a  fs_register()].*
f330: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76  * and [sqlite3_v
f340: 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d  fs_unregister()]
f350: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61   interfaces mana
f360: 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20  ge this list.** 
f370: 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65  in a thread-safe
f380: 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69   way.  The [sqli
f390: 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20  te3_vfs_find()] 
f3a0: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61  interface.** sea
f3b0: 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20  rches the list. 
f3c0: 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70   Neither the app
f3d0: 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f  lication code no
f3e0: 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70  r the VFS.** imp
f3f0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75  lementation shou
f400: 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74  ld use the pNext
f410: 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
f420: 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20  The pNext field 
f430: 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c  is the only fiel
f440: 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  d in the sqlite3
f450: 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72  _vfs.** structur
f460: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  e that SQLite wi
f470: 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20  ll ever modify. 
f480: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c   SQLite will onl
f490: 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d  y access.** or m
f4a0: 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64  odify this field
f4b0: 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61   while holding a
f4c0: 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74   particular stat
f4d0: 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65  ic mutex..** The
f4e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
f4f0: 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79  uld never modify
f500: 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e   anything within
f510: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
f520: 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20  .** object once 
f530: 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62  the object has b
f540: 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a  een registered..
f550: 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20  **.** The zName 
f560: 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20  field holds the 
f570: 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20  name of the VFS 
f580: 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d  module.  The nam
f590: 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69  e must.** be uni
f5a0: 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56  que across all V
f5b0: 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a  FS modules..**.*
f5c0: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
f5d0: 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69  xOpen]].** ^SQLi
f5e0: 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  te guarantees th
f5f0: 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  at the zFilename
f600: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
f610: 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  pen.** is either
f620: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
f630: 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e  or string obtain
f640: 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c  ed.** from xFull
f650: 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20  Pathname() with 
f660: 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66  an optional suff
f670: 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66  ix added..** ^If
f680: 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64   a suffix is add
f690: 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e  ed to the zFilen
f6a0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69  ame parameter, i
f6b0: 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73  t will.** consis
f6c0: 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d  t of a single "-
f6d0: 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c  " character foll
f6e0: 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20  owed by no more 
f6f0: 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61  than.** 11 alpha
f700: 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22  numeric and/or "
f710: 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -" characters..*
f720: 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65  * ^SQLite furthe
f730: 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  r guarantees tha
f740: 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  t.** the string 
f750: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e  will be valid an
f760: 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69  d unchanged unti
f770: 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a  l xClose() is.**
f780: 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65   called. Because
f790: 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   of the previous
f7a0: 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68   sentence,.** th
f7b0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
f7c0: 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72   can safely stor
f7d0: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  e a pointer to t
f7e0: 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  he.** filename i
f7f0: 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65  f it needs to re
f800: 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e  member the filen
f810: 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ame for some rea
f820: 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a  son..** If the z
f830: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
f840: 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61  er to xOpen is a
f850: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
f860: 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74  en xOpen.** must
f870: 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20   invent its own 
f880: 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66  temporary name f
f890: 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57  or the file.  ^W
f8a0: 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20  henever the .** 
f8b0: 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  xFilename parame
f8c0: 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77  ter is NULL it w
f8d0: 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20  ill also be the 
f8e0: 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  case that the.**
f8f0: 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
f900: 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53   will include [S
f910: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
f920: 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a  EONCLOSE]..**.**
f930: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
f940: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69  ent to xOpen() i
f950: 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73  ncludes all bits
f960: 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66   set in.** the f
f970: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
f980: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
f990: 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71  2()].  Or if [sq
f9a0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
f9b0: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
f9c0: 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20  n16()] is used, 
f9d0: 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75  then flags inclu
f9e0: 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20  des at least.** 
f9f0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
fa00: 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
fa10: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20  E_OPEN_CREATE]. 
fa20: 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f  .** If xOpen() o
fa30: 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64  pens a file read
fa40: 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65  -only then it se
fa50: 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f  ts *pOutFlags to
fa60: 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  .** include [SQL
fa70: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
fa80: 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20  Y].  Other bits 
fa90: 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61  in *pOutFlags ma
faa0: 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  y be set..**.** 
fab0: 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  ^(SQLite will al
fac0: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
fad0: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
fae0: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  s to the xOpen()
faf0: 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64  .** call, depend
fb00: 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63  ing on the objec
fb10: 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a  t being opened:.
fb20: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
fb30: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
fb40: 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _MAIN_DB].** <li
fb50: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
fb60: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  MAIN_JOURNAL].**
fb70: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
fb80: 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20  PEN_TEMP_DB].** 
fb90: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
fba0: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d  EN_TEMP_JOURNAL]
fbb0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
fbc0: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
fbd0: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
fbe0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
fbf0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
fc00: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53  [SQLITE_OPEN_MAS
fc10: 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  TER_JOURNAL].** 
fc20: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
fc30: 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  EN_WAL].** </ul>
fc40: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c  )^.**.** The fil
fc50: 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61  e I/O implementa
fc60: 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65  tion can use the
fc70: 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61   object type fla
fc80: 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20  gs to.** change 
fc90: 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73  the way it deals
fca0: 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f   with files.  Fo
fcb0: 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  r example, an ap
fcc0: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61  plication.** tha
fcd0: 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20  t does not care 
fce0: 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f  about crash reco
fcf0: 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b  very or rollback
fd00: 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74   might make.** t
fd10: 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75  he open of a jou
fd20: 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f  rnal file a no-o
fd30: 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68  p.  Writes to th
fd40: 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  is journal would
fd50: 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f  .** also be no-o
fd60: 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65  ps, and any atte
fd70: 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20  mpt to read the 
fd80: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65  journal would re
fd90: 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49  turn.** SQLITE_I
fda0: 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d  OERR.  Or the im
fdb0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67  plementation mig
fdc0: 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61  ht recognize tha
fdd0: 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  t a database.** 
fde0: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69  file will be doi
fdf0: 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20  ng page-aligned 
fe00: 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64  sector reads and
fe10: 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e   writes in a ran
fe20: 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64  dom.** order and
fe30: 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20   set up its I/O 
fe40: 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64  subsystem accord
fe50: 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ingly..**.** SQL
fe60: 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61  ite might also a
fe70: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
fe80: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
fe90: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
fea0: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
feb0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50   <li> [SQLITE_OP
fec0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
fed0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
fee0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
fef0: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
ff00: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
ff10: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
ff20: 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20   flag means the 
ff30: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  file should be.*
ff40: 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69  * deleted when i
ff50: 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54  t is closed.  ^T
ff60: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
ff70: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
ff80: 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f  * will be set fo
ff90: 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73  r TEMP databases
ffa0: 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e   and their journ
ffb0: 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a  als, transient.*
ffc0: 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64  * databases, and
ffd0: 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a   subjournals..**
ffe0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
fff0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
10000 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20   flag is always 
10010 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74  used in conjunct
10020 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ion.** with the 
10030 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
10040 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68  ATE] flag, which
10050 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74   are both direct
10060 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20  ly.** analogous 
10070 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e  to the O_EXCL an
10080 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20  d O_CREAT flags 
10090 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65  of the POSIX ope
100a0 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65  n().** API.  The
100b0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
100c0 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65  LUSIVE flag, whe
100d0 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68  n paired with th
100e0 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45  e .** SQLITE_OPE
100f0 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65  N_CREATE, is use
10100 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
10110 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61  at file should a
10120 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61  lways.** be crea
10130 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74  ted, and that it
10140 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20   is an error if 
10150 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  it already exist
10160 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e  s..** It is <i>n
10170 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69  ot</i> used to i
10180 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65  ndicate the file
10190 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65   should be opene
101a0 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73  d .** for exclus
101b0 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a  ive access..**.*
101c0 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73  * ^At least szOs
101d0 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65  File bytes of me
101e0 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74  mory are allocat
101f0 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
10200 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71  to hold the  [sq
10210 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75  lite3_file] stru
10220 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20  cture passed as 
10230 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67  the third.** arg
10240 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20  ument to xOpen. 
10250 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   The xOpen metho
10260 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  d does not have 
10270 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74  to.** allocate t
10280 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74  he structure; it
10290 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c   should just fil
102a0 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74  l it in.  Note t
102b0 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e  hat.** the xOpen
102c0 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74   method must set
102d0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
102e0 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69  e.pMethods to ei
102f0 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20  ther.** a valid 
10300 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
10310 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74  ods] object or t
10320 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d  o NULL.  xOpen m
10330 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65  ust do.** this e
10340 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20  ven if the open 
10350 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65  fails.  SQLite e
10360 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20  xpects that the 
10370 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
10380 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74  thods.** element
10390 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
103a0 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72  fter xOpen retur
103b0 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ns regardless of
103c0 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20   the success.** 
103d0 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68  or failure of th
103e0 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a  e xOpen call..**
103f0 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66  .** [[sqlite3_vf
10400 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e  s.xAccess]].** ^
10410 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
10420 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20  nt to xAccess() 
10430 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  may be [SQLITE_A
10440 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a  CCESS_EXISTS].**
10450 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65   to test for the
10460 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20   existence of a 
10470 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  file, or [SQLITE
10480 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
10490 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68  E] to.** test wh
104a0 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
104b0 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
104c0 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54  table, or [SQLIT
104d0 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a  E_ACCESS_READ].*
104e0 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65  * to test whethe
104f0 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c  r a file is at l
10500 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20  east readable.  
10510 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65   The file can be
10520 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e   a.** directory.
10530 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .**.** ^SQLite w
10540 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63  ill always alloc
10550 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50  ate at least mxP
10560 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20  athname+1 bytes 
10570 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75  for the.** outpu
10580 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61  t buffer xFullPa
10590 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61  thname.  The exa
105a0 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f  ct size of the o
105b0 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
105c0 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61  is also passed a
105d0 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f  s a parameter to
105e0 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20   both  methods. 
105f0 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  If the output bu
10600 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c  ffer.** is not l
10610 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51  arge enough, [SQ
10620 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73  LITE_CANTOPEN] s
10630 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
10640 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73  d. Since this is
10650 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61  .** handled as a
10660 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20   fatal error by 
10670 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c  SQLite, vfs impl
10680 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
10690 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74  ld endeavor.** t
106a0 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62  o prevent this b
106b0 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68  y setting mxPath
106c0 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63  name to a suffic
106d0 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c  iently large val
106e0 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  ue..**.** The xR
106f0 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c  andomness(), xSl
10700 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54  eep(), xCurrentT
10710 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72  ime(), and xCurr
10720 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a  entTimeInt64().*
10730 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  * interfaces are
10740 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20   not strictly a 
10750 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65  part of the file
10760 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79  system, but they
10770 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64   are.** included
10780 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75   in the VFS stru
10790 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65  cture for comple
107a0 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78  teness..** The x
107b0 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e  Randomness() fun
107c0 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74  ction attempts t
107d0 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20  o return nBytes 
107e0 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64  bytes.** of good
107f0 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e  -quality randomn
10800 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20  ess into zOut.  
10810 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
10820 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61   is.** the actua
10830 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  l number of byte
10840 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
10850 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  obtained..** The
10860 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
10870 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
10880 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c  ing thread to sl
10890 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65  eep for at.** le
108a0 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ast the number o
108b0 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67  f microseconds g
108c0 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72  iven.  ^The xCur
108d0 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65  rentTime().** me
108e0 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a  thod returns a J
108f0 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72  ulian Day Number
10900 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74   for the current
10910 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61   date and time a
10920 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20  s.** a floating 
10930 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20  point value..** 
10940 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
10950 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
10960 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69  returns, as an i
10970 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69  nteger, the Juli
10980 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72  an.** Day Number
10990 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38   multiplied by 8
109a0 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d  6400000 (the num
109b0 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
109c0 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d  nds in .** a 24-
109d0 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20  hour day).  .** 
109e0 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
109f0 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d   the xCurrentTim
10a00 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
10a10 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65  to get the curre
10a20 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74  nt.** date and t
10a30 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68  ime if that meth
10a40 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  od is available 
10a50 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20  (if iVersion is 
10a60 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72  2 or .** greater
10a70 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f   and the functio
10a80 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
10a90 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20   NULL) and will 
10aa0 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20  fall back.** to 
10ab0 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69  xCurrentTime() i
10ac0 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  f xCurrentTimeIn
10ad0 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c  t64() is unavail
10ae0 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  able..**.** ^The
10af0 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xSetSystemCall(
10b00 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c  ), xGetSystemCal
10b10 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79  l(), and xNestSy
10b20 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72  stemCall() inter
10b30 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74  faces.** are not
10b40 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c   used by the SQL
10b50 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65  ite core.  These
10b60 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66   optional interf
10b70 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65  aces are provide
10b80 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53  d.** by some VFS
10b90 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65  es to facilitate
10ba0 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20   testing of the 
10bb0 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65  VFS code. By ove
10bc0 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74  rriding .** syst
10bd0 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75  em calls with fu
10be0 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74  nctions under it
10bf0 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73  s control, a tes
10c00 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a  t program can.**
10c10 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73   simulate faults
10c20 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69   and error condi
10c30 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64  tions that would
10c40 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69   otherwise be di
10c50 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d  fficult.** or im
10c60 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75  possible to indu
10c70 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20  ce.  The set of 
10c80 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61  system calls tha
10c90 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64  t can be overrid
10ca0 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72  den.** varies fr
10cb0 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e  om one VFS to an
10cc0 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20  other, and from 
10cd0 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  one version of t
10ce0 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74  he same VFS to t
10cf0 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70  he.** next.  App
10d00 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75  lications that u
10d10 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  se these interfa
10d20 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70  ces must be prep
10d30 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20  ared for any.** 
10d40 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  or all of these 
10d50 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65  interfaces to be
10d60 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65   NULL or for the
10d70 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63  ir behavior to c
10d80 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e  hange.** from on
10d90 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65  e release to the
10da0 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74   next.  Applicat
10db0 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74  ions must not at
10dc0 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a  tempt to access.
10dd0 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  ** any of these 
10de0 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69  methods if the i
10df0 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56  Version of the V
10e00 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  FS is less than 
10e10 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  3..*/.typedef st
10e20 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
10e30 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79   sqlite3_vfs;.ty
10e40 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
10e50 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
10e60 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20  )(void);.struct 
10e70 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20  sqlite3_vfs {.  
10e80 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20  int iVersion;   
10e90 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75           /* Stru
10ea0 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75  cture version nu
10eb0 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20  mber (currently 
10ec0 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73  3) */.  int szOs
10ed0 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20  File;           
10ee0 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63   /* Size of subc
10ef0 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66  lassed sqlite3_f
10f00 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50  ile */.  int mxP
10f10 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20  athname;        
10f20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c    /* Maximum fil
10f30 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74  e pathname lengt
10f40 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76  h */.  sqlite3_v
10f50 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20  fs *pNext;      
10f60 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72  /* Next register
10f70 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73  ed VFS */.  cons
10f80 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20  t char *zName;  
10f90 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
10fa0 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c  this virtual fil
10fb0 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f  e system */.  vo
10fc0 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
10fd0 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65         /* Pointe
10fe0 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e  r to application
10ff0 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a  -specific data *
11000 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  /.  int (*xOpen)
11010 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
11020 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
11030 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  , sqlite3_file*,
11040 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
11050 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
11060 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e  pOutFlags);.  in
11070 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c  t (*xDelete)(sql
11080 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
11090 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
110a0 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e  t syncDir);.  in
110b0 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c  t (*xAccess)(sql
110c0 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
110d0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
110e0 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52  t flags, int *pR
110f0 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
11100 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73  xFullPathname)(s
11110 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
11120 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
11130 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a  int nOut, char *
11140 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28  zOut);.  void *(
11150 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65  *xDlOpen)(sqlite
11160 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
11170 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a  ar *zFilename);.
11180 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f    void (*xDlErro
11190 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
111a0 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
111b0 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f   *zErrMsg);.  vo
111c0 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73  id (*(*xDlSym)(s
111d0 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64  qlite3_vfs*,void
111e0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
111f0 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a  Symbol))(void);.
11200 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73    void (*xDlClos
11210 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
11220 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28   void*);.  int (
11230 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71  *xRandomness)(sq
11240 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
11250 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75  nByte, char *zOu
11260 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65  t);.  int (*xSle
11270 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ep)(sqlite3_vfs*
11280 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e  , int microsecon
11290 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75  ds);.  int (*xCu
112a0 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74  rrentTime)(sqlit
112b0 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a  e3_vfs*, double*
112c0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c  );.  int (*xGetL
112d0 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65  astError)(sqlite
112e0 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61  3_vfs*, int, cha
112f0 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  r *);.  /*.  ** 
11300 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
11310 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
11320 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   1 of the sqlite
11330 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a  _vfs object.  **
11340 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
11350 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  ose that follow 
11360 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72  are added in ver
11370 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a  sion 2 or later.
11380 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75    */.  int (*xCu
11390 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28  rrentTimeInt64)(
113a0 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71  sqlite3_vfs*, sq
113b0 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20  lite3_int64*);. 
113c0 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
113d0 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
113e0 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64  n versions 1 and
113f0 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   2 of the sqlite
11400 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
11410 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72  * Those below ar
11420 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20  e for version 3 
11430 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a  and greater..  *
11440 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79  /.  int (*xSetSy
11450 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
11460 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
11470 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
11480 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b  e3_syscall_ptr);
11490 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  .  sqlite3_sysca
114a0 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73  ll_ptr (*xGetSys
114b0 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
114c0 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
114d0 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e  r *zName);.  con
114e0 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74  st char *(*xNext
114f0 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
11500 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
11510 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
11520 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
11530 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
11540 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f   versions 1 thro
11550 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c  ugh 3 of the sql
11560 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
11570 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20    ** New fields 
11580 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
11590 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  in future versio
115a0 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f  ns.  The iVersio
115b0 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c  n.  ** value wil
115c0 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e  l increment when
115d0 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e  ever this happen
115e0 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  s. .  */.};../*.
115f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
11600 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65  gs for the xAcce
11610 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a  ss VFS method.**
11620 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
11630 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20  r constants can 
11640 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74  be used as the t
11650 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
11660 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73  o.** the xAccess
11670 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73   method of an [s
11680 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
11690 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d  ct.  They determ
116a0 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64  ine.** what kind
116b0 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20   of permissions 
116c0 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
116d0 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f  od is looking fo
116e0 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  r..** With SQLIT
116f0 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c  E_ACCESS_EXISTS,
11700 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
11710 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68  hod.** simply ch
11720 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
11730 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a   file exists..**
11740 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
11750 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74  ESS_READWRITE, t
11760 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
11770 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
11780 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69  her the named di
11790 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20  rectory is both 
117a0 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
117b0 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68  table.** (in oth
117c0 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c  er words, if fil
117d0 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c  es can be added,
117e0 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65   removed, and re
117f0 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20  named within.** 
11800 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a  the directory)..
11810 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  ** The SQLITE_AC
11820 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63  CESS_READWRITE c
11830 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65  onstant is curre
11840 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62  ntly used only b
11850 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73  y the.** [temp_s
11860 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
11870 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74  ragma], though t
11880 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65  his could change
11890 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20   in a future.** 
118a0 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
118b0 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  e..** With SQLIT
118c0 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74  E_ACCESS_READ, t
118d0 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
118e0 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
118f0 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20  her the file is 
11900 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53  readable.  The S
11910 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
11920 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a  D constant is.**
11930 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65   currently unuse
11940 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67  d, though it mig
11950 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20  ht be used in a 
11960 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
11970 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  f.** SQLite..*/.
11980 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
11990 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20  CCESS_EXISTS    
119a0 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
119b0 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
119c0 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79  E 1   /* Used by
119d0 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f   PRAGMA temp_sto
119e0 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a  re_directory */.
119f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
11a00 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20  CCESS_READ      
11a10 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f  2   /* Unused */
11a20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
11a30 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
11a40 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74  xShmLock VFS met
11a50 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
11a60 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
11a70 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72  s define the var
11a80 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65  ious locking ope
11a90 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77  rations.** allow
11aa0 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f  ed by the xShmLo
11ab0 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71  ck method of [sq
11ac0 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
11ad0 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f  ].  The.** follo
11ae0 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c  wing are the onl
11af0 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74  y legal combinat
11b00 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f  ions of flags to
11b10 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b   the.** xShmLock
11b20 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
11b30 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  ul>.** <li>  SQL
11b40 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
11b50 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
11b60 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
11b70 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
11b80 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
11b90 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
11ba0 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
11bb0 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
11bc0 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
11bd0 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
11be0 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
11bf0 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  E.** </ul>.**.**
11c00 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c   When unlocking,
11c10 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44   the same SHARED
11c20 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c   or EXCLUSIVE fl
11c30 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c  ag must be suppl
11c40 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69  ied as.** was gi
11c50 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65  ven on the corre
11c60 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20  sponding lock.  
11c70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c  .**.** The xShmL
11c80 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74  ock method can t
11c90 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
11ca0 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53  n unlocked and S
11cb0 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77  HARED or.** betw
11cc0 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
11cd0 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20   EXCLUSIVE.  It 
11ce0 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f  cannot transitio
11cf0 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44  n between SHARED
11d00 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56  .** and EXCLUSIV
11d10 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  E..*/.#define SQ
11d20 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
11d30 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
11d40 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
11d50 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
11d60 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  e SQLITE_SHM_SHA
11d70 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66  RED       4.#def
11d80 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  ine SQLITE_SHM_E
11d90 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f  XCLUSIVE    8../
11da0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
11db0 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20  aximum xShmLock 
11dc0 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20  index.**.** The 
11dd0 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
11de0 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  on [sqlite3_io_m
11df0 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20  ethods] may use 
11e00 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65  values.** betwee
11e10 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70  n 0 and this upp
11e20 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20  er bound as its 
11e30 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e  "offset" argumen
11e40 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  t..** The SQLite
11e50 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72   core will never
11e60 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75   attempt to acqu
11e70 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61  ire or release a
11e80 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65  .** lock outside
11e90 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a   of this range.*
11ea0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
11eb0 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20  _SHM_NLOCK      
11ec0 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    8.../*.** CAPI
11ed0 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65  3REF: Initialize
11ee0 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
11ef0 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ary.**.** ^The s
11f00 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
11f10 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74  e() routine init
11f20 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53  ializes the.** S
11f30 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
11f40 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75  ^The sqlite3_shu
11f50 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a  tdown() routine.
11f60 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61  ** deallocates a
11f70 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61  ny resources tha
11f80 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64  t were allocated
11f90 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
11fa0 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65  ialize()..** The
11fb0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
11fc0 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20  designed to aid 
11fd0 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  in process initi
11fe0 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a  alization and.**
11ff0 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62   shutdown on emb
12000 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20  edded systems.  
12010 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c  Workstation appl
12020 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a  ications using.*
12030 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c  * SQLite normall
12040 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f  y do not need to
12050 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f   invoke either o
12060 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
12070 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ..**.** A call t
12080 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
12090 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66  lize() is an "ef
120a0 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
120b0 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69   it is.** the fi
120c0 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
120d0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
120e0 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20   invoked during 
120f0 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a  the lifetime of.
12100 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20  ** the process, 
12110 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20  or if it is the 
12120 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
12130 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
12140 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f  is invoked.** fo
12150 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74  llowing a call t
12160 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
12170 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e  wn().  ^(Only an
12180 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a   effective call.
12190 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e  ** of sqlite3_in
121a0 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20  itialize() does 
121b0 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  any initializati
121c0 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63  on.  All other c
121d0 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d  alls.** are harm
121e0 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a  less no-ops.)^.*
121f0 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
12200 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
12210 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
12220 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
12230 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63  s the first.** c
12240 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
12250 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20  hutdown() since 
12260 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
12270 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20  _initialize().  
12280 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66  ^(Only.** an eff
12290 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73  ective call to s
122a0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
122b0 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69  ) does any deini
122c0 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20  tialization..** 
122d0 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20  All other valid 
122e0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
122f0 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20  _shutdown() are 
12300 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
12310 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )^.**.** The sql
12320 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
12330 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  ) interface is t
12340 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73  hreadsafe, but s
12350 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
12360 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68  ).** is not.  Th
12370 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
12380 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  wn() interface m
12390 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  ust only be call
123a0 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e  ed from a.** sin
123b0 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c  gle thread.  All
123c0 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20   open [database 
123d0 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73  connections] mus
123e0 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20  t be closed and 
123f0 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c  all.** other SQL
12400 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75  ite resources mu
12410 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  st be deallocate
12420 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b  d prior to invok
12430 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ing.** sqlite3_s
12440 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a  hutdown()..**.**
12450 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69   Among other thi
12460 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e  ngs, ^sqlite3_in
12470 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20  itialize() will 
12480 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
12490 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69  3_os_init().  Si
124a0 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65  milarly, ^sqlite
124b0 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
124c0 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69  will invoke sqli
124d0 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a  te3_os_end()..**
124e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
124f0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
12500 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53  utine returns [S
12510 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
12520 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72  cess..** ^If for
12530 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71   some reason, sq
12540 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
12550 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
12560 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68  initialize.** th
12570 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61  e library (perha
12580 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  ps it is unable 
12590 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65  to allocate a ne
125a0 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75  eded resource su
125b0 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78  ch.** as a mutex
125c0 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ) it returns an 
125d0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68  [error code] oth
125e0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
125f0 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  OK]..**.** ^The 
12600 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
12610 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  ze() routine is 
12620 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c  called internall
12630 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a  y by many other.
12640 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
12650 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20  aces so that an 
12660 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61  application usua
12670 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  lly does not nee
12680 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73  d to.** invoke s
12690 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
126a0 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46  e() directly.  F
126b0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c  or example, [sql
126c0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
126d0 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e  calls sqlite3_in
126e0 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68  itialize() so th
126f0 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
12700 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
12710 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61  ically.** initia
12720 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69  lized when [sqli
12730 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63  te3_open()] is c
12740 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20  alled if it has 
12750 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a  not be initializ
12760 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20  ed.** already.  
12770 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c  ^However, if SQL
12780 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
12790 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
127a0 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a  _OMIT_AUTOINIT].
127b0 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
127c0 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  option, then the
127d0 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73   automatic calls
127e0 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
127f0 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20  ialize().** are 
12800 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20  omitted and the 
12810 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
12820 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e   call sqlite3_in
12830 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
12840 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  tly.** prior to 
12850 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
12860 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
12870 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70  .  For maximum p
12880 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69  ortability,.** i
12890 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
128a0 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
128b0 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65  ns always invoke
128c0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
128d0 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c  ize().** directl
128e0 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  y prior to using
128f0 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
12900 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75  e interface.  Fu
12910 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a  ture releases.**
12920 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72   of SQLite may r
12930 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e  equire this.  In
12940 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
12950 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62  e behavior exhib
12960 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  ited.** when SQL
12970 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
12980 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49  with [SQLITE_OMI
12990 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68  T_AUTOINIT] migh
129a0 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20  t become the.** 
129b0 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
129c0 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
129d0 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
129e0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e..**.** The sql
129f0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72  ite3_os_init() r
12a00 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72  outine does oper
12a10 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
12a20 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c  cific.** initial
12a30 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53  ization of the S
12a40 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
12a50 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  The sqlite3_os_e
12a60 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  nd().** routine 
12a70 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63  undoes the effec
12a80 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  t of sqlite3_os_
12a90 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c  init().  Typical
12aa0 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72   tasks.** perfor
12ab0 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75  med by these rou
12ac0 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c  tines include al
12ad0 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c  location or deal
12ae0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73  location.** of s
12af0 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c  tatic resources,
12b00 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
12b10 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  of global variab
12b20 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20  les,.** setting 
12b30 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71  up a default [sq
12b40 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c  lite3_vfs] modul
12b50 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70  e, or setting up
12b60 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f  .** a default co
12b70 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e  nfiguration usin
12b80 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  g [sqlite3_confi
12b90 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  g()]..**.** The 
12ba0 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
12bb0 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ld never invoke 
12bc0 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f  either sqlite3_o
12bd0 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73  s_init().** or s
12be0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
12bf0 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61  directly.  The a
12c00 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
12c10 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a  d only invoke.**
12c20 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
12c30 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ize() and sqlite
12c40 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54  3_shutdown().  T
12c50 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
12c60 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  it().** interfac
12c70 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f  e is called auto
12c80 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
12c90 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
12ca0 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ) and.** sqlite3
12cb0 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c  _os_end() is cal
12cc0 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  led by sqlite3_s
12cd0 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72  hutdown().  Appr
12ce0 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65  opriate.** imple
12cf0 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73  mentations for s
12d00 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
12d10 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
12d20 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69  end().** are bui
12d30 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77  lt into SQLite w
12d40 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c  hen it is compil
12d50 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e  ed for Unix, Win
12d60 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a  dows, or OS/2..*
12d70 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62  * When [custom b
12d80 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f  uilds | built fo
12d90 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d  r other platform
12da0 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65  s].** (using the
12db0 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45   [SQLITE_OS_OTHE
12dc0 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  R=1] compile-tim
12dd0 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65  e.** option) the
12de0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
12df0 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61  t supply a suita
12e00 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
12e10 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  on for.** sqlite
12e20 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
12e30 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
12e40 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  .  An applicatio
12e50 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d  n-supplied.** im
12e60 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
12e70 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
12e80 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ) or sqlite3_os_
12e90 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65  end().** must re
12ea0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
12eb0 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
12ec0 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f  some other [erro
12ed0 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20  r code] upon.** 
12ee0 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49  failure..*/.SQLI
12ef0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
12f00 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
12f10 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69  3_initialize(voi
12f20 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  d);.SQLITE_API i
12f30 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
12f40 4c 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  L sqlite3_shutdo
12f50 77 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  wn(void);.SQLITE
12f60 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
12f70 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
12f80 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 53  os_init(void);.S
12f90 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
12fa0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
12fb0 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64  ite3_os_end(void
12fc0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
12fd0 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20  EF: Configuring 
12fe0 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
12ff0 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ry.**.** The sql
13000 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
13010 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
13020 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63  to make global c
13030 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
13040 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74  changes to SQLit
13050 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75  e in order to tu
13060 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  ne SQLite to the
13070 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20   specific needs 
13080 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
13090 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61  ation.  The defa
130a0 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
130b0 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  n is recommended
130c0 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70   for most.** app
130d0 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f  lications and so
130e0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
130f0 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63   usually not nec
13100 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a  essary.  It is.*
13110 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75  * provided to su
13120 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69  pport rare appli
13130 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75  cations with unu
13140 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  sual needs..**.*
13150 2a 20 3c 62 3e 54 68 65 20 73 71 6c 69 74 65 33  * <b>The sqlite3
13160 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
13170 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61  ace is not threa
13180 64 73 61 66 65 2e 20 54 68 65 20 61 70 70 6c 69  dsafe. The appli
13190 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65  cation.** must e
131a0 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74  nsure that no ot
131b0 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
131c0 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65  faces are invoke
131d0 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68  d by other.** th
131e0 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69  reads while sqli
131f0 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
13200 72 75 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a  running.</b>.**.
13210 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
13220 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
13230 65 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65  e.** may only be
13240 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74   invoked prior t
13250 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61  o library initia
13260 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  lization using.*
13270 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  * [sqlite3_initi
13280 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
13290 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73  r shutdown by [s
132a0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
132b0 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  )]..** ^If sqlit
132c0 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63  e3_config() is c
132d0 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
132e0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
132f0 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a  )] and before.**
13300 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
13310 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69  wn()] then it wi
13320 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ll return SQLITE
13330 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65  _MISUSE..** Note
13340 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20  , however, that 
13350 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  ^sqlite3_config(
13360 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  ) can be called 
13370 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a  as part of the.*
13380 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
13390 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   of an applicati
133a0 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69  on-defined [sqli
133b0 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a  te3_os_init()]..
133c0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
133d0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
133e0 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
133f0 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63  an integer.** [c
13400 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13410 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d  ion] that determ
13420 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f  ines.** what pro
13430 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20  perty of SQLite 
13440 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75  is to be configu
13450 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74  red.  Subsequent
13460 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61   arguments.** va
13470 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
13480 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69  the [configurati
13490 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e  on option].** in
134a0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
134b0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  ent..**.** ^When
134c0 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   a configuration
134d0 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20   option is set, 
134e0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
134f0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
13500 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  _OK]..** ^If the
13510 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f   option is unkno
13520 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20  wn or SQLite is 
13530 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68  unable to set th
13540 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e  e option.** then
13550 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
13560 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f  turns a non-zero
13570 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
13580 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
13590 20 53 51 4c 49 54 45 5f 43 44 45 43 4c 20 73 71   SQLITE_CDECL sq
135a0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74  lite3_config(int
135b0 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
135c0 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
135d0 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  re database conn
135e0 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f  ections.** METHO
135f0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
13600 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f   The sqlite3_db_
13610 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
13620 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
13630 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ke configuration
13640 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61  .** changes to a
13650 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
13660 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74  ction].  The int
13670 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61  erface is simila
13680 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
13690 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70  _config()] excep
136a0 74 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67  t that the chang
136b0 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69  es apply to a si
136c0 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ngle.** [databas
136d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73  e connection] (s
136e0 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20  pecified in the 
136f0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e  first argument).
13700 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
13710 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
13720 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
13730 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65  D,V,...)  is the
13740 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f  .** [SQLITE_DBCO
13750 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c  NFIG_LOOKASIDE |
13760 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76   configuration v
13770 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65  erb] - an intege
13780 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20  r code .** that 
13790 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61  indicates what a
137a0 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61  spect of the [da
137b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
137c0 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66  n] is being conf
137d0 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65  igured..** Subse
137e0 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20  quent arguments 
137f0 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f  vary depending o
13800 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  n the configurat
13810 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20  ion verb..**.** 
13820 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65  ^Calls to sqlite
13830 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65  3_db_config() re
13840 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69  turn SQLITE_OK i
13850 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
13860 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e   the call is con
13870 73 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66  sidered successf
13880 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ul..*/.SQLITE_AP
13890 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 43 44 45  I int SQLITE_CDE
138a0 43 4c 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  CL sqlite3_db_co
138b0 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69  nfig(sqlite3*, i
138c0 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  nt op, ...);../*
138d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
138e0 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
138f0 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41  Routines.**.** A
13900 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
13910 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
13920 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
13930 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a  between SQLite.*
13940 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20  * and low-level 
13950 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
13960 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  n routines..**.*
13970 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
13980 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e   used in only on
13990 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53  e place in the S
139a0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
139b0 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  .** A pointer to
139c0 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
139d0 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74  this object is t
139e0 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  he argument to.*
139f0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
13a00 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f  g()] when the co
13a10 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
13a20 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  on is.** [SQLITE
13a30 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20  _CONFIG_MALLOC] 
13a40 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
13a50 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a  G_GETMALLOC].  .
13a60 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61  ** By creating a
13a70 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
13a80 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64  is object.** and
13a90 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
13aa0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
13ab0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
13ac0 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e  ALLOC]).** durin
13ad0 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  g configuration,
13ae0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
13af0 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61  can specify an a
13b00 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
13b10 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
13b20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51  subsystem for SQ
13b30 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20  Lite to use for 
13b40 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79  all of its.** dy
13b50 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65  namic memory nee
13b60 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  ds..**.** Note t
13b70 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73  hat SQLite comes
13b80 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62   with several [b
13b90 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
13ba0 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68  llocators].** th
13bb0 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79  at are perfectly
13bc0 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68   adequate for th
13bd0 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d  e overwhelming m
13be0 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  ajority of appli
13bf0 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74  cations.** and t
13c00 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20  hat this object 
13c10 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74  is only useful t
13c20 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74  o a tiny minorit
13c30 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
13c40 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61  s.** with specia
13c50 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  lized memory all
13c60 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d  ocation requirem
13c70 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65  ents.  This obje
13c80 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73  ct is.** also us
13c90 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
13ca0 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f  g of SQLite in o
13cb0 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20  rder to specify 
13cc0 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
13cd0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
13ce0 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65  or that simulate
13cf0 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d  s memory out-of-
13d00 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e  memory condition
13d10 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f  s in.** order to
13d20 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c   verify that SQL
13d30 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61  ite recovers gra
13d40 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63  cefully from suc
13d50 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e  h.** conditions.
13d60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c  .**.** The xMall
13d70 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e  oc, xRealloc, an
13d80 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20  d xFree methods 
13d90 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74  must work like t
13da0 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20  he.** malloc(), 
13db0 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72  realloc() and fr
13dc0 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66  ee() functions f
13dd0 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
13de0 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e   C library..** ^
13df0 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
13e00 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e  s that the secon
13e10 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
13e20 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77   xRealloc is alw
13e30 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75  ays a value retu
13e40 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20  rned by a prior 
13e50 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70  call to xRoundup
13e60 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68  ..**.** xSize sh
13e70 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
13e80 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
13e90 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
13ea0 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75  ation.** previou
13eb0 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
13ec0 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65  m xMalloc or xRe
13ed0 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f  alloc.  The allo
13ee0 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73  cated size.** is
13ef0 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74   always at least
13f00 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72   as big as the r
13f10 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75  equested size bu
13f20 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e  t may be larger.
13f30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e  .**.** The xRoun
13f40 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72  dup method retur
13f50 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65  ns what would be
13f60 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
13f70 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f  ize of.** a memo
13f80 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69  ry allocation gi
13f90 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ven a particular
13fa0 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e   requested size.
13fb0 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a    Most memory.**
13fc0 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
13fd0 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  d up memory allo
13fe0 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74  cations at least
13ff0 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c   to the next mul
14000 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20  tiple.** of 8.  
14010 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20  Some allocators 
14020 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61  round up to a la
14030 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72  rger multiple or
14040 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32   to a power of 2
14050 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72  ..** Every memor
14060 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
14070 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74  uest coming in t
14080 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f  hrough [sqlite3_
14090 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20  malloc()].** or 
140a0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
140b0 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20  ()] first calls 
140c0 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52  xRoundup.  If xR
140d0 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30  oundup returns 0
140e0 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65  , .** that cause
140f0 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  s the correspond
14100 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ing memory alloc
14110 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a  ation to fail..*
14120 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d  *.** The xInit m
14130 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65  ethod initialize
14140 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
14150 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61  ocator.  For exa
14160 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68  mple,.** it migh
14170 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  t allocate any r
14180 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f  equire mutexes o
14190 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74  r initialize int
141a0 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74  ernal data.** st
141b0 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78  ructures.  The x
141c0 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
141d0 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69  is invoked (indi
141e0 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73  rectly) by.** [s
141f0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
14200 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65  )] and should de
14210 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73  allocate any res
14220 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a  ources acquired.
14230 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68  ** by xInit.  Th
14240 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74  e pAppData point
14250 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68  er is used as th
14260 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
14270 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64   to.** xInit and
14280 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a   xShutdown..**.*
14290 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74  * SQLite holds t
142a0 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
142b0 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20  _STATIC_MASTER] 
142c0 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e  mutex when it in
142d0 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e  vokes.** the xIn
142e0 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68  it method, so th
142f0 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e  e xInit method n
14300 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61  eed not be threa
14310 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78  dsafe.  The.** x
14320 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
14330 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66  is only called f
14340 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  rom [sqlite3_shu
14350 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64  tdown()] so it d
14360 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20  oes.** not need 
14370 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65  to be threadsafe
14380 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c   either.  For al
14390 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c  l other methods,
143a0 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73   SQLite.** holds
143b0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54   the [SQLITE_MUT
143c0 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d  EX_STATIC_MEM] m
143d0 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20  utex as long as 
143e0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  the.** [SQLITE_C
143f0 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
14400 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
14410 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ption is turned 
14420 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20  on (which.** it 
14430 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61  is by default) a
14440 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64  nd so the method
14450 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  s are automatica
14460 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a  lly serialized..
14470 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b  ** However, if [
14480 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
14490 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61  MSTATUS] is disa
144a0 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f  bled, then the o
144b0 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20  ther.** methods 
144c0 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
144d0 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20  fe or else make 
144e0 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67  their own arrang
144f0 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65  ements for.** se
14500 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a  rialization..**.
14510 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  ** SQLite will n
14520 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69  ever invoke xIni
14530 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  t() more than on
14540 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e  ce without an in
14550 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c  tervening.** cal
14560 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29  l to xShutdown()
14570 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
14580 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
14590 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
145a0 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  mem_methods;.str
145b0 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
145c0 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64  methods {.  void
145d0 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74   *(*xMalloc)(int
145e0 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65  );         /* Me
145f0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14600 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  function */.  vo
14610 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64  id (*xFree)(void
14620 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  *);          /* 
14630 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c  Free a prior all
14640 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  ocation */.  voi
14650 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76  d *(*xRealloc)(v
14660 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52  oid*,int);  /* R
14670 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74  esize an allocat
14680 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
14690 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Size)(void*);   
146a0 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72          /* Retur
146b0 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e  n the size of an
146c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
146d0 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29   int (*xRoundup)
146e0 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20  (int);          
146f0 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75  /* Round up requ
14700 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f  est size to allo
14710 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20  cation size */. 
14720 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f   int (*xInit)(vo
14730 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
14740 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68  /* Initialize th
14750 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
14760 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  or */.  void (*x
14770 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29  Shutdown)(void*)
14780 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74  ;      /* Deinit
14790 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
147a0 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
147b0 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
147c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
147d0 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78  /* Argument to x
147e0 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74  Init() and xShut
147f0 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  down() */.};../*
14800 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
14810 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
14820 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ons.** KEYWORDS:
14830 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   {configuration 
14840 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68  option}.**.** Th
14850 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
14860 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
14870 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
14880 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
14890 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
148a0 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  sed as the first
148b0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
148c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
148d0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
148e0 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
148f0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
14900 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
14910 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
14920 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
14930 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
14940 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
14950 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
14960 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
14970 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
14980 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
14990 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
149a0 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
149b0 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
149c0 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
149d0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  The [sqlite3_con
149e0 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
149f0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
14a00 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
14a10 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
14a20 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
14a30 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
14a40 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
14a50 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
14a60 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
14a70 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
14a80 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51  ETHREAD]] <dt>SQ
14a90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
14aa0 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  LETHREAD</dt>.**
14ab0 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
14ac0 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
14ad0 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
14ae0 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
14af0 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
14b00 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65   mode] to Single
14b10 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
14b20 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
14b30 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
14b40 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53  exing and puts S
14b50 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64  QLite into a mod
14b60 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f  e where it can o
14b70 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62  nly be used.** b
14b80 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61  y a single threa
14b90 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  d.   ^If SQLite 
14ba0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
14bb0 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
14bc0 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
14bd0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
14be0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
14bf0 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
14c00 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
14c10 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b   to change the [
14c20 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
14c30 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74  from its default
14c40 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e  .** value of Sin
14c50 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73  gle-thread and s
14c60 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
14c70 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
14c80 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
14c90 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
14ca0 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
14cb0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
14cc0 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  D.** configurati
14cd0 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
14ce0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14cf0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
14d00 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
14d10 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
14d20 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
14d30 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
14d40 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
14d50 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
14d60 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
14d70 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
14d80 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e  to Multi-thread.
14d90 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
14da0 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
14db0 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61   mutexing on [da
14dc0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14dd0 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
14de0 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
14df0 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  cts..** The appl
14e00 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f  ication is respo
14e10 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61  nsible for seria
14e20 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f  lizing access to
14e30 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
14e40 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
14e50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
14e60 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72  nts].  But other
14e70 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
14e80 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20  enabled so that 
14e90 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73  SQLite will be s
14ea0 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20  afe to use in a 
14eb0 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a  multi-threaded.*
14ec0 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73  * environment as
14ed0 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20   long as no two 
14ee0 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20  threads attempt 
14ef0 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a  to use the same.
14f00 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
14f10 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20  nection] at the 
14f20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20  same time.  ^If 
14f30 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
14f40 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
14f50 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
14f60 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
14f70 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
14f80 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
14f90 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
14fa0 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
14fb0 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20  he Multi-thread 
14fc0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
14fd0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
14fe0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
14ff0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
15000 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
15010 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
15020 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
15030 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74  HREAD configurat
15040 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
15050 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
15060 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
15070 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
15080 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
15090 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
150a0 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
150b0 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
150c0 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
150d0 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
150e0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
150f0 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e  o Serialized. In
15100 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
15110 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65  is option enable
15120 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73  s.** all mutexes
15130 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72   including the r
15140 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65  ecursive.** mute
15150 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  xes on [database
15160 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
15170 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
15180 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
15190 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28  * In this mode (
151a0 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66  which is the def
151b0 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65  ault when SQLite
151c0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
151d0 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  h.** [SQLITE_THR
151e0 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20  EADSAFE=1]) the 
151f0 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
15200 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61  ill itself seria
15210 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  lize access.** t
15220 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  o [database conn
15230 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
15240 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
15250 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a  s] so that the.*
15260 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  * application is
15270 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65   free to use the
15280 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
15290 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74  connection] or t
152a0 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70  he.** same [prep
152b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
152c0 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  in different thr
152d0 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
152e0 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51   time..** ^If SQ
152f0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
15300 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
15310 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
15320 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
15330 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
15340 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
15350 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
15360 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
15370 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   Serialized [thr
15380 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64  eading mode] and
15390 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
153a0 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
153b0 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
153c0 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
153d0 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43   the.** SQLITE_C
153e0 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
153f0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
15400 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
15410 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
15420 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53  G_MALLOC]] <dt>S
15430 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
15440 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
15450 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
15460 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69  NFIG_MALLOC opti
15470 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
15480 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
15490 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65   is .** a pointe
154a0 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
154b0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
154c0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
154d0 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20  ructure..** The 
154e0 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
154f0 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
15500 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  e low-level memo
15510 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
15520 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
15530 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a  d in place of.**
15540 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
15550 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
15560 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
15570 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b  e.)^ ^SQLite mak
15580 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72  es.** its own pr
15590 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
155a0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
155b0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
155c0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
155d0 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b  .** before the [
155e0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
155f0 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c  ] call returns.<
15600 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
15610 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
15620 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  LLOC]] <dt>SQLIT
15630 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
15640 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
15650 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
15660 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70  FIG_GETMALLOC op
15670 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
15680 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
15690 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
156a0 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
156b0 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
156c0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
156d0 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65  tructure..** The
156e0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
156f0 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
15700 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
15710 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
15720 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20   defined memory 
15730 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
15740 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
15750 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
15760 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
15770 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  e default memory
15780 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
15790 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
157a0 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75  rapper that simu
157b0 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61  lations memory a
157c0 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72  llocation failur
157d0 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d  e or.** tracks m
157e0 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72  emory usage, for
157f0 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a   example. </dd>.
15800 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
15810 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
15820 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
15830 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64  FIG_MEMSTATUS</d
15840 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
15850 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
15860 4d 53 54 41 54 55 53 20 6f 70 74 69 6f 6e 20 74  MSTATUS option t
15870 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75  akes single argu
15880 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
15890 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 65 64  ,.** interpreted
158a0 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77   as a boolean, w
158b0 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20  hich enables or 
158c0 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c  disables the col
158d0 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65  lection of.** me
158e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
158f0 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68  statistics. ^(Wh
15900 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  en memory alloca
15910 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
15920 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2c  are.** disabled,
15930 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   the following S
15940 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
15950 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72   become non-oper
15960 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75  ational:.**   <u
15970 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  l>.**   <li> [sq
15980 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
15990 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  d()].**   <li> [
159a0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
159b0 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20  ighwater()].**  
159c0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
159d0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
159e0 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
159f0 71 6c 69 74 65 33 5f 73 74 61 74 75 73 36 34 28  qlite3_status64(
15a00 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a  )].**   </ul>)^.
15a10 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ** ^Memory alloc
15a20 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
15a30 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20   are enabled by 
15a40 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53  default unless S
15a50 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70  QLite is.** comp
15a60 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
15a70 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41  E_DEFAULT_MEMSTA
15a80 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20  TUS]=0 in which 
15a90 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  case memory.** a
15aa0 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
15ab0 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65  tics are disable
15ac0 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
15ad0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
15ae0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
15af0 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ATCH]] <dt>SQLIT
15b00 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
15b10 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
15b20 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
15b30 5f 53 43 52 41 54 43 48 20 6f 70 74 69 6f 6e 20  _SCRATCH option 
15b40 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
15b50 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
15b60 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20  .** that SQLite 
15b70 63 61 6e 20 75 73 65 20 66 6f 72 20 73 63 72 61  can use for scra
15b80 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 5e 28 54  tch memory.  ^(T
15b90 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
15ba0 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 53  rguments.** to S
15bb0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
15bc0 41 54 43 48 3a 20 20 41 20 70 6f 69 6e 74 65 72  ATCH:  A pointer
15bd0 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c   an 8-byte.** al
15be0 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66  igned memory buf
15bf0 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74  fer from which t
15c00 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  he scratch alloc
15c10 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a  ations will be.*
15c20 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a  * drawn, the siz
15c30 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63  e of each scratc
15c40 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a  h allocation (sz
15c50 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61  ),.** and the ma
15c60 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
15c70 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
15c80 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54 68  ons (N).)^.** Th
15c90 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
15ca0 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74   must be a point
15cb0 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  er to an 8-byte 
15cc0 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a  aligned buffer.*
15cd0 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a  * of at least sz
15ce0 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  *N bytes of memo
15cf0 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ry..** ^SQLite w
15d00 69 6c 6c 20 6e 6f 74 20 75 73 65 20 6d 6f 72 65  ill not use more
15d10 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63   than one scratc
15d20 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74 68  h buffers per th
15d30 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  read..** ^SQLite
15d40 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75   will never requ
15d50 65 73 74 20 61 20 73 63 72 61 74 63 68 20 62 75  est a scratch bu
15d60 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72  ffer that is mor
15d70 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65  e than 6.** time
15d80 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70  s the database p
15d90 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66  age size..** ^If
15da0 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65   SQLite needs ne
15db0 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  eds additional.*
15dc0 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  * scratch memory
15dd0 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
15de0 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73  provided by this
15df0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
15e00 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20  ption, then .** 
15e10 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
15e20 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20  )] will be used 
15e30 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65  to obtain the me
15e40 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 70 3e 0a  mory needed.<p>.
15e50 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 61 70 70  ** ^When the app
15e60 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76 69 64 65  lication provide
15e70 73 20 61 6e 79 20 61 6d 6f 75 6e 74 20 6f 66 20  s any amount of 
15e80 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 75  scratch memory u
15e90 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 43  sing.** SQLITE_C
15ea0 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 2c 20 53  ONFIG_SCRATCH, S
15eb0 51 4c 69 74 65 20 61 76 6f 69 64 73 20 75 6e 6e  QLite avoids unn
15ec0 65 63 65 73 73 61 72 79 20 6c 61 72 67 65 0a 2a  ecessary large.*
15ed0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
15ee0 63 7c 68 65 61 70 20 61 6c 6c 6f 63 61 74 69 6f  c|heap allocatio
15ef0 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 20 63 61 6e  ns]..** This can
15f00 20 68 65 6c 70 20 5b 52 6f 62 73 6f 6e 20 70 72   help [Robson pr
15f10 6f 6f 66 7c 70 72 65 76 65 6e 74 20 6d 65 6d 6f  oof|prevent memo
15f20 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
15f30 69 6c 75 72 65 73 5d 20 64 75 65 20 74 6f 20 68  ilures] due to h
15f40 65 61 70 0a 2a 2a 20 66 72 61 67 6d 65 6e 74 61  eap.** fragmenta
15f50 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d 6f  tion in low-memo
15f60 72 79 20 65 6d 62 65 64 64 65 64 20 73 79 73 74  ry embedded syst
15f70 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ems..** </dd>.**
15f80 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15f90 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20  FIG_PAGECACHE]] 
15fa0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15fb0 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e  G_PAGECACHE</dt>
15fc0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
15fd0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
15fe0 43 41 43 48 45 20 6f 70 74 69 6f 6e 20 73 70 65  CACHE option spe
15ff0 63 69 66 69 65 73 20 61 20 6d 65 6d 6f 72 79 20  cifies a memory 
16000 70 6f 6f 6c 0a 2a 2a 20 74 68 61 74 20 53 51 4c  pool.** that SQL
16010 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20  ite can use for 
16020 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  the database pag
16030 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65  e cache with the
16040 20 64 65 66 61 75 6c 74 20 70 61 67 65 0a 2a 2a   default page.**
16050 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
16060 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73  ation.  .** This
16070 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
16080 70 74 69 6f 6e 20 69 73 20 61 20 6e 6f 2d 6f 70  ption is a no-op
16090 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   if an applicati
160a0 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a  on-define page.*
160b0 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  * cache implemen
160c0 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64  tation is loaded
160d0 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49   using the [SQLI
160e0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
160f0 32 5d 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72  2]..** ^There ar
16100 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
16110 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  s to SQLITE_CONF
16120 49 47 5f 50 41 47 45 43 41 43 48 45 3a 20 41 20  IG_PAGECACHE: A 
16130 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 38 2d  pointer to.** 8-
16140 62 79 74 65 20 61 6c 69 67 6e 65 64 20 6d 65 6d  byte aligned mem
16150 6f 72 79 20 28 70 4d 65 6d 29 2c 20 74 68 65 20  ory (pMem), the 
16160 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67  size of each pag
16170 65 20 63 61 63 68 65 20 6c 69 6e 65 20 28 73 7a  e cache line (sz
16180 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6e 75  ),.** and the nu
16190 6d 62 65 72 20 6f 66 20 63 61 63 68 65 20 6c 69  mber of cache li
161a0 6e 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20  nes (N)..** The 
161b0 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  sz argument shou
161c0 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f  ld be the size o
161d0 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61  f the largest da
161e0 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28  tabase page.** (
161f0 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62  a power of two b
16200 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 36  etween 512 and 6
16210 35 35 33 36 29 20 70 6c 75 73 20 73 6f 6d 65 20  5536) plus some 
16220 65 78 74 72 61 20 62 79 74 65 73 20 66 6f 72 20  extra bytes for 
16230 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61  each.** page hea
16240 64 65 72 2e 20 20 5e 54 68 65 20 6e 75 6d 62 65  der.  ^The numbe
16250 72 20 6f 66 20 65 78 74 72 61 20 62 79 74 65 73  r of extra bytes
16260 20 6e 65 65 64 65 64 20 62 79 20 74 68 65 20 70   needed by the p
16270 61 67 65 20 68 65 61 64 65 72 0a 2a 2a 20 63 61  age header.** ca
16280 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20  n be determined 
16290 75 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f 43 4f  using [SQLITE_CO
162a0 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
162b0 5a 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 68 61  Z]..** ^It is ha
162c0 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72  rmless, apart fr
162d0 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65  om the wasted me
162e0 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20 74 68 65  mory,.** for the
162f0 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 74 6f   sz parameter to
16300 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20   be larger than 
16310 6e 65 63 65 73 73 61 72 79 2e 20 20 54 68 65 20  necessary.  The 
16320 70 4d 65 6d 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  pMem.** argument
16330 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
16340 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f  a NULL pointer o
16350 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  r a pointer to a
16360 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67  n 8-byte.** alig
16370 6e 65 64 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d  ned block of mem
16380 6f 72 79 20 6f 66 20 61 74 20 6c 65 61 73 74 20  ory of at least 
16390 73 7a 2a 4e 20 62 79 74 65 73 2c 20 6f 74 68 65  sz*N bytes, othe
163a0 72 77 69 73 65 0a 2a 2a 20 73 75 62 73 65 71 75  rwise.** subsequ
163b0 65 6e 74 20 62 65 68 61 76 69 6f 72 20 69 73 20  ent behavior is 
163c0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 57  undefined..** ^W
163d0 68 65 6e 20 70 4d 65 6d 20 69 73 20 6e 6f 74 20  hen pMem is not 
163e0 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c  NULL, SQLite wil
163f0 6c 20 73 74 72 69 76 65 20 74 6f 20 75 73 65 20  l strive to use 
16400 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69  the memory provi
16410 64 65 64 0a 2a 2a 20 74 6f 20 73 61 74 69 73 66  ded.** to satisf
16420 79 20 70 61 67 65 20 63 61 63 68 65 20 6e 65 65  y page cache nee
16430 64 73 2c 20 66 61 6c 6c 69 6e 67 20 62 61 63 6b  ds, falling back
16440 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
16450 6c 6f 63 28 29 5d 20 69 66 0a 2a 2a 20 61 20 70  loc()] if.** a p
16460 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65 20 69  age cache line i
16470 73 20 6c 61 72 67 65 72 20 74 68 61 6e 20 73 7a  s larger than sz
16480 20 62 79 74 65 73 20 6f 72 20 69 66 20 61 6c 6c   bytes or if all
16490 20 6f 66 20 74 68 65 20 70 4d 65 6d 20 62 75 66   of the pMem buf
164a0 66 65 72 0a 2a 2a 20 69 73 20 65 78 68 61 75 73  fer.** is exhaus
164b0 74 65 64 2e 0a 2a 2a 20 5e 49 66 20 70 4d 65 6d  ted..** ^If pMem
164c0 20 69 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69   is NULL and N i
164d0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
164e0 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
164f0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 64 6f 65  onnection.** doe
16500 73 20 61 6e 20 69 6e 69 74 69 61 6c 20 62 75 6c  s an initial bul
16510 6b 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72  k allocation for
16520 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
16530 72 79 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ry.** from [sqli
16540 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 75  te3_malloc()] su
16550 66 66 69 63 69 65 6e 74 20 66 6f 72 20 4e 20 63  fficient for N c
16560 61 63 68 65 20 6c 69 6e 65 73 20 69 66 20 4e 20  ache lines if N 
16570 69 73 20 70 6f 73 69 74 69 76 65 20 6f 72 0a 2a  is positive or.*
16580 2a 20 6f 66 20 2d 31 30 32 34 2a 4e 20 62 79 74  * of -1024*N byt
16590 65 73 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74  es if N is negat
165a0 69 76 65 2c 20 2e 20 5e 49 66 20 61 64 64 69 74  ive, . ^If addit
165b0 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61  ional.** page ca
165c0 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65  che memory is ne
165d0 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74  eded beyond what
165e0 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
165f0 74 68 65 20 69 6e 69 74 69 61 6c 0a 2a 2a 20 61  the initial.** a
16600 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20  llocation, then 
16610 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b  SQLite goes to [
16620 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
16630 5d 20 73 65 70 61 72 61 74 65 6c 79 20 66 6f 72  ] separately for
16640 20 65 61 63 68 0a 2a 2a 20 61 64 64 69 74 69 6f   each.** additio
16650 6e 61 6c 20 63 61 63 68 65 20 6c 69 6e 65 2e 20  nal cache line. 
16660 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
16670 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
16680 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
16690 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a  NFIG_HEAP</dt>.*
166a0 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49  * <dd> ^The SQLI
166b0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f  TE_CONFIG_HEAP o
166c0 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
166d0 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
166e0 62 75 66 66 65 72 20 0a 2a 2a 20 74 68 61 74 20  buffer .** that 
166f0 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
16700 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64  for all of its d
16710 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c  ynamic memory al
16720 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 0a 2a  location needs.*
16730 2a 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70  * beyond those p
16740 72 6f 76 69 64 65 64 20 66 6f 72 20 62 79 20 5b  rovided for by [
16750 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
16760 52 41 54 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b 53  RATCH] and.** [S
16770 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
16780 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68 65  ECACHE]..** ^The
16790 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
167a0 45 41 50 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e  EAP option is on
167b0 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
167c0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
167d0 65 64 0a 2a 2a 20 77 69 74 68 20 65 69 74 68 65  ed.** with eithe
167e0 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  r [SQLITE_ENABLE
167f0 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 20 5b 53 51  _MEMSYS3] or [SQ
16800 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53  LITE_ENABLE_MEMS
16810 59 53 35 5d 20 61 6e 64 20 72 65 74 75 72 6e 73  YS5] and returns
16820 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
16830 52 5d 20 69 66 20 69 6e 76 6f 6b 65 64 20 6f 74  R] if invoked ot
16840 68 65 72 77 69 73 65 2e 0a 2a 2a 20 5e 54 68 65  herwise..** ^The
16850 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
16860 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45  uments to SQLITE
16870 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3a 0a 2a 2a  _CONFIG_HEAP:.**
16880 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   An 8-byte align
16890 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  ed pointer to th
168a0 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65  e memory,.** the
168b0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
168c0 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62   in the memory b
168d0 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d  uffer, and the m
168e0 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
168f0 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74  n size..** ^If t
16900 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72  he first pointer
16910 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69   (the memory poi
16920 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74  nter) is NULL, t
16930 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72  hen SQLite rever
16940 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69  ts.** to using i
16950 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  ts default memor
16960 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65  y allocator (the
16970 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
16980 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29   implementation)
16990 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79  ,.** undoing any
169a0 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f   prior invocatio
169b0 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  n of [SQLITE_CON
169c0 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49  FIG_MALLOC].  ^I
169d0 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  f the.** memory 
169e0 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
169f0 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 61 6c 74  ULL then the alt
16a00 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a  ernative memory.
16a10 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20  ** allocator is 
16a20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c  engaged to handl
16a30 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73  e all of SQLites
16a40 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
16a50 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65  on needs..** The
16a60 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28   first pointer (
16a70 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  the memory point
16a80 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67  er) must be alig
16a90 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
16aa0 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20  .** boundary or 
16ab0 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
16ac0 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69  ior of SQLite wi
16ad0 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e  ll be undefined.
16ae0 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20  .** The minimum 
16af0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
16b00 69 73 20 63 61 70 70 65 64 20 61 74 20 32 2a 2a  is capped at 2**
16b10 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76  12. Reasonable v
16b20 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65  alues.** for the
16b30 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
16b40 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a 2a  ion size are 2**
16b50 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c  5 through 2**8.<
16b60 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
16b70 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
16b80 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
16b90 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a  NFIG_MUTEX</dt>.
16ba0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
16bb0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
16bc0 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  X option takes a
16bd0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
16be0 20 77 68 69 63 68 20 69 73 20 61 0a 2a 2a 20 70   which is a.** p
16bf0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
16c00 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
16c10 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
16c20 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a  ods] structure..
16c30 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  ** The argument 
16c40 73 70 65 63 69 66 69 65 73 20 61 6c 74 65 72 6e  specifies altern
16c50 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20  ative low-level 
16c60 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74  mutex routines t
16c70 6f 20 62 65 20 75 73 65 64 0a 2a 2a 20 69 6e 20  o be used.** in 
16c80 70 6c 61 63 65 20 74 68 65 20 6d 75 74 65 78 20  place the mutex 
16c90 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
16ca0 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e  nto SQLite.)^  ^
16cb0 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
16cc0 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f  opy of.** the co
16cd0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71  ntent of the [sq
16ce0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
16cf0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62  ods] structure b
16d00 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74  efore the call t
16d10 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
16d20 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e  nfig()] returns.
16d30 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
16d40 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
16d50 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
16d60 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
16d70 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
16d80 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
16d90 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e  n then.** the en
16da0 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75  tire mutexing su
16db0 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74  bsystem is omitt
16dc0 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c  ed from the buil
16dd0 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c  d and hence call
16de0 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
16df0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20  _config()] with 
16e00 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
16e10 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72  G_MUTEX configur
16e20 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c  ation option wil
16e30 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
16e40 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e  ITE_ERROR].</dd>
16e50 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
16e60 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d  CONFIG_GETMUTEX]
16e70 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
16e80 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74  FIG_GETMUTEX</dt
16e90 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
16ea0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
16eb0 54 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61  TMUTEX option ta
16ec0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
16ed0 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69  ument which.** i
16ee0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
16ef0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
16f00 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
16f10 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
16f20 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71  ure.  The.** [sq
16f30 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
16f40 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ods].** structur
16f50 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  e is filled with
16f60 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64   the currently d
16f70 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75  efined mutex rou
16f80 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73  tines.)^.** This
16f90 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
16fa0 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
16fb0 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65  the default mute
16fc0 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  x allocation.** 
16fd0 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
16fe0 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20  wrapper used to 
16ff0 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67  track mutex usag
17000 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63  e for performanc
17010 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f  e.** profiling o
17020 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65  r testing, for e
17030 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51  xample.   ^If SQ
17040 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
17050 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
17060 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
17070 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
17080 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
17090 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
170a0 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
170b0 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
170c0 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
170d0 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
170e0 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
170f0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
17100 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
17110 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
17120 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  TEX configuratio
17130 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a  n option will.**
17140 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
17150 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ERROR].</dd>.**.
17160 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
17170 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c  IG_LOOKASIDE]] <
17180 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
17190 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
171a0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
171b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
171c0 41 53 49 44 45 20 6f 70 74 69 6f 6e 20 74 61 6b  ASIDE option tak
171d0 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  es two arguments
171e0 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 0a   that determine.
171f0 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20 73  ** the default s
17200 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65  ize of lookaside
17210 20 6d 65 6d 6f 72 79 20 6f 6e 20 65 61 63 68 20   memory on each 
17220 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
17230 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69  tion]..** The fi
17240 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
17250 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
17260 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
17270 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68  ffer slot and th
17280 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20  e second is the 
17290 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
172a0 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20  ts allocated to 
172b0 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
172c0 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 53  nnection.)^  ^(S
172d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
172e0 4b 41 53 49 44 45 0a 2a 2a 20 73 65 74 73 20 74  KASIDE.** sets t
172f0 68 65 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69  he <i>default</i
17300 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65  > lookaside size
17310 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42  . The [SQLITE_DB
17320 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
17330 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f 20 5b  ].** option to [
17340 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
17350 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64  g()] can be used
17360 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c   to change the l
17370 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66  ookaside.** conf
17380 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64  iguration on ind
17390 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69  ividual connecti
173a0 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a  ons.)^ </dd>.**.
173b0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
173c0 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 74  IG_PCACHE2]] <dt
173d0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
173e0 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c  CACHE2</dt>.** <
173f0 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45  dd> ^(The SQLITE
17400 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20  _CONFIG_PCACHE2 
17410 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
17420 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
17430 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f  hich is .** a po
17440 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c  inter to an [sql
17450 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
17460 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54  ods2] object.  T
17470 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69  his object speci
17480 66 69 65 73 0a 2a 2a 20 74 68 65 20 69 6e 74 65  fies.** the inte
17490 72 66 61 63 65 20 74 6f 20 61 20 63 75 73 74 6f  rface to a custo
174a0 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  m page cache imp
174b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a 2a  lementation.)^.*
174c0 2a 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  * ^SQLite makes 
174d0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73  a copy of the [s
174e0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
174f0 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 3c  thods2] object.<
17500 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
17510 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
17520 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49  ACHE2]] <dt>SQLI
17530 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
17540 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHE2</dt>.** <dd
17550 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
17560 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
17570 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
17580 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
17590 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f  which.** is a po
175a0 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c  inter to an [sql
175b0 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
175c0 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53  ods2] object.  S
175d0 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 0a  QLite copies of.
175e0 2a 2a 20 74 68 65 20 63 75 72 72 65 6e 74 20 70  ** the current p
175f0 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
17600 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68  entation into th
17610 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64  at object.)^ </d
17620 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
17630 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c  E_CONFIG_LOG]] <
17640 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
17650 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _LOG</dt>.** <dd
17660 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  > The SQLITE_CON
17670 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69  FIG_LOG option i
17680 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67  s used to config
17690 75 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a 2a  ure the SQLite.*
176a0 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20  * global [error 
176b0 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53  log]..** (^The S
176c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
176d0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
176e0 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70  o arguments: a p
176f0 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66  ointer to a.** f
17700 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63  unction with a c
17710 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66  all signature of
17720 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69   void(*)(void*,i
17730 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  nt,const char*),
17740 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74   .** and a point
17750 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20  er to void. ^If 
17760 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  the function poi
17770 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
17780 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b  , it is.** invok
17790 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
177a0 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73  og()] to process
177b0 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76   each logging ev
177c0 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ent.  ^If the.**
177d0 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
177e0 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b  r is NULL, the [
177f0 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69  sqlite3_log()] i
17800 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73  nterface becomes
17810 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68   a no-op..** ^Th
17820 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74  e void pointer t
17830 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e  hat is the secon
17840 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51  d argument to SQ
17850 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
17860 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72  is.** passed thr
17870 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73  ough as the firs
17880 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
17890 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
178a0 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
178b0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76   function whenev
178c0 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e  er that function
178d0 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54   is invoked.  ^T
178e0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
178f0 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f  ter to.** the lo
17900 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73  gger function is
17910 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66   a copy of the f
17920 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
17930 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  o the correspond
17940 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
17950 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20  log()] call and 
17960 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62  is intended to b
17970 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  e a [result code
17980 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65  ] or an.** [exte
17990 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
179a0 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70  ].  ^The third p
179b0 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20  arameter passed 
179c0 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73  to the logger is
179d0 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20  .** log message 
179e0 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67  after formatting
179f0 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e   via [sqlite3_sn
17a00 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68  printf()]..** Th
17a10 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67  e SQLite logging
17a20 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
17a30 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65  t reentrant; the
17a40 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
17a50 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20  .** supplied by 
17a60 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
17a70 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20  must not invoke 
17a80 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72  any SQLite inter
17a90 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75  face..** In a mu
17aa0 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 70  lti-threaded app
17ab0 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70  lication, the ap
17ac0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
17ad0 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63  d logger.** func
17ae0 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72  tion must be thr
17af0 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a  eadsafe. </dd>.*
17b00 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
17b10 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53  NFIG_URI]] <dt>S
17b20 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
17b30 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 51  .** <dd>^(The SQ
17b40 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20  LITE_CONFIG_URI 
17b50 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
17b60 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f  ingle argument o
17b70 66 20 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20 49  f type int..** I
17b80 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  f non-zero, then
17b90 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
17ba0 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65   globally enable
17bb0 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d 65  d. If the parame
17bc0 74 65 72 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20  ter is zero,.** 
17bd0 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e  then URI handlin
17be0 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69  g is globally di
17bf0 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52  sabled.)^ ^If UR
17c00 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
17c10 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c 65  obally.** enable
17c20 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73  d, all filenames
17c30 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69   passed to [sqli
17c40 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
17c50 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
17c60 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ,.** [sqlite3_op
17c70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70  en16()] or.** sp
17c80 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74 20  ecified as part 
17c90 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d  of [ATTACH] comm
17ca0 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70 72  ands are interpr
17cb0 65 74 65 64 20 61 73 20 55 52 49 73 2c 20 72 65  eted as URIs, re
17cc0 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77  gardless.** of w
17cd0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
17ce0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
17cf0 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20  RI] flag is set 
17d00 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
17d10 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
17d20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69  is opened. ^If i
17d30 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69  t is globally di
17d40 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65  sabled, filename
17d50 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e  s are.** only in
17d60 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49  terpreted as URI
17d70 73 20 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f  s if the SQLITE_
17d80 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73  OPEN_URI flag is
17d90 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a   set when the.**
17da0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
17db0 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20  tion is opened. 
17dc0 5e 28 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52  ^(By default, UR
17dd0 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
17de0 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c  obally.** disabl
17df0 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20  ed. The default 
17e00 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61  value may be cha
17e10 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e  nged by compilin
17e20 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  g with the.** [S
17e30 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73  QLITE_USE_URI] s
17e40 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e  ymbol defined.)^
17e50 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
17e60 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
17e70 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74  INDEX_SCAN]] <dt
17e80 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43  >SQLITE_CONFIG_C
17e90 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
17ea0 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  AN.** <dd>^The S
17eb0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
17ec0 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
17ed0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
17ee0 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 0a 2a  single integer.*
17ef0 2a 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  * argument which
17f00 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
17f10 61 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20  as a boolean in 
17f20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 20  order to enable 
17f30 6f 72 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68  or disable.** th
17f40 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e  e use of coverin
17f50 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75  g indices for fu
17f60 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20 69  ll table scans i
17f70 6e 20 74 68 65 20 71 75 65 72 79 20 6f 70 74 69  n the query opti
17f80 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 64  mizer..** ^The d
17f90 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 69  efault setting i
17fa0 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20  s determined.** 
17fb0 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 41  by the [SQLITE_A
17fc0 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  LLOW_COVERING_IN
17fd0 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c  DEX_SCAN] compil
17fe0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f  e-time option, o
17ff0 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20  r is "on".** if 
18000 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  that compile-tim
18010 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74  e option is omit
18020 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c  ted..** The abil
18030 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20 74  ity to disable t
18040 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69  he use of coveri
18050 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66  ng indices for f
18060 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 0a  ull table scans.
18070 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20 73 6f  ** is because so
18080 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 63  me incorrectly c
18090 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70 70 6c  oded legacy appl
180a0 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d  ications might m
180b0 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68  alfunction.** wh
180c0 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74  en the optimizat
180d0 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20  ion is enabled. 
180e0 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20 61   Providing the a
180f0 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73  bility to.** dis
18100 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 7a  able the optimiz
18110 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65  ation allows the
18120 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61 70   older, buggy ap
18130 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 74  plication code t
18140 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75  o work.** withou
18150 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77 69  t change even wi
18160 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e  th newer version
18170 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  s of SQLite..**.
18180 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
18190 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51  IG_PCACHE]] [[SQ
181a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
181b0 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  CACHE]].** <dt>S
181c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
181d0 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43  CHE and SQLITE_C
181e0 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a  ONFIG_GETPCACHE.
181f0 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70  ** <dd> These op
18200 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65  tions are obsole
18210 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f  te and should no
18220 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65 77  t be used by new
18230 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61   code..** They a
18240 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20  re retained for 
18250 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
18260 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65 20  ibility but are 
18270 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c  now no-ops..** <
18280 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
18290 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f  ITE_CONFIG_SQLLO
182a0 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  G]].** <dt>SQLIT
182b0 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a  E_CONFIG_SQLLOG.
182c0 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
182d0 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  on is only avail
182e0 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20 69  able if sqlite i
182f0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
18300 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
18310 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72  NABLE_SQLLOG] pr
18320 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  e-processor macr
18330 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66  o defined. The f
18340 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68  irst argument sh
18350 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69  ould.** be a poi
18360 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69  nter to a functi
18370 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28  on of type void(
18380 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
18390 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  *,const char*, i
183a0 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  nt)..** The seco
183b0 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20  nd should be of 
183c0 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68  type (void*). Th
183d0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  e callback is in
183e0 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62  voked by the lib
183f0 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65  rary.** in three
18400 20 73 65 70 61 72 61 74 65 20 63 69 72 63 75 6d   separate circum
18410 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66  stances, identif
18420 69 65 64 20 62 79 20 74 68 65 20 76 61 6c 75 65  ied by the value
18430 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a   passed as the.*
18440 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  * fourth paramet
18450 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74  er. If the fourt
18460 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 30  h parameter is 0
18470 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
18480 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
18490 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  * passed as the 
184a0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
184b0 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70  has just been op
184c0 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64 20  ened. The third 
184d0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e  argument.** poin
184e0 74 73 20 74 6f 20 61 20 62 75 66 66 65 72 20 63  ts to a buffer c
184f0 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61  ontaining the na
18500 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64  me of the main d
18510 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66  atabase file. If
18520 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70   the.** fourth p
18530 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74  arameter is 1, t
18540 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  hen the SQL stat
18550 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20 74  ement that the t
18560 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a  hird parameter.*
18570 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20  * points to has 
18580 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63 75 74  just been execut
18590 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66  ed. Or, if the f
185a0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
185b0 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  is 2, then.** th
185c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69  e connection bei
185d0 6e 67 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ng passed as the
185e0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
185f0 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65  r is being close
18600 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20  d. The.** third 
18610 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 61 73  parameter is pas
18620 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73  sed NULL In this
18630 20 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d 70   case.  An examp
18640 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73  le of using this
18650 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
18660 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  n option can be 
18670 73 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65 73  seen in the "tes
18680 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72  t_sqllog.c" sour
18690 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68  ce file in.** th
186a0 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69  e canonical SQLi
186b0 74 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 3c  te source tree.<
186c0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
186d0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
186e0 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  SIZE]].** <dt>SQ
186f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
18700 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51  _SIZE.** <dd>^SQ
18710 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
18720 5f 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f 20  _SIZE takes two 
18730 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 28  64-bit integer (
18740 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20 76  sqlite3_int64) v
18750 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 72  alues.** that ar
18760 65 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 6d  e the default mm
18770 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28 74  ap size limit (t
18780 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69  he default setti
18790 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d  ng for.** [PRAGM
187a0 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e  A mmap_size]) an
187b0 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c  d the maximum al
187c0 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 20  lowed mmap size 
187d0 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64  limit..** ^The d
187e0 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 63  efault setting c
187f0 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e  an be overridden
18800 20 62 79 20 65 61 63 68 20 64 61 74 61 62 61 73   by each databas
18810 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69  e connection usi
18820 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68 65  ng.** either the
18830 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69   [PRAGMA mmap_si
18840 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20  ze] command, or 
18850 62 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  by using the.** 
18860 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d  [SQLITE_FCNTL_MM
18870 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f  AP_SIZE] file co
18880 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61  ntrol.  ^(The ma
18890 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d  ximum allowed mm
188a0 61 70 20 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c 20  ap size.** will 
188b0 62 65 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e  be silently trun
188c0 63 61 74 65 64 20 69 66 20 6e 65 63 65 73 73 61  cated if necessa
188d0 72 79 20 73 6f 20 74 68 61 74 20 69 74 20 64 6f  ry so that it do
188e0 65 73 20 6e 6f 74 20 65 78 63 65 65 64 20 74 68  es not exceed th
188f0 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  e.** compile-tim
18900 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73  e maximum mmap s
18910 69 7a 65 20 73 65 74 20 62 79 20 74 68 65 0a 2a  ize set by the.*
18920 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d  * [SQLITE_MAX_MM
18930 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65  AP_SIZE] compile
18940 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a  -time option.)^.
18950 2a 2a 20 5e 49 66 20 65 69 74 68 65 72 20 61 72  ** ^If either ar
18960 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 6f  gument to this o
18970 70 74 69 6f 6e 20 69 73 20 6e 65 67 61 74 69 76  ption is negativ
18980 65 2c 20 74 68 65 6e 20 74 68 61 74 20 61 72 67  e, then that arg
18990 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e  ument is.** chan
189a0 67 65 64 20 74 6f 20 69 74 73 20 63 6f 6d 70 69  ged to its compi
189b0 6c 65 2d 74 69 6d 65 20 64 65 66 61 75 6c 74 2e  le-time default.
189c0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
189d0 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
189e0 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  PSIZE]].** <dt>S
189f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
18a00 33 32 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c  32_HEAPSIZE.** <
18a10 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
18a20 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
18a30 53 49 5a 45 20 6f 70 74 69 6f 6e 20 69 73 20 6f  SIZE option is o
18a40 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
18a50 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f   SQLite is.** co
18a60 6d 70 69 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f  mpiled for Windo
18a70 77 73 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ws with the [SQL
18a80 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43  ITE_WIN32_MALLOC
18a90 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20  ] pre-processor 
18aa0 6d 61 63 72 6f 0a 2a 2a 20 64 65 66 69 6e 65 64  macro.** defined
18ab0 2e 20 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  . ^SQLITE_CONFIG
18ac0 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20  _WIN32_HEAPSIZE 
18ad0 74 61 6b 65 73 20 61 20 33 32 2d 62 69 74 20 75  takes a 32-bit u
18ae0 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20  nsigned integer 
18af0 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73 70  value.** that sp
18b00 65 63 69 66 69 65 73 20 74 68 65 20 6d 61 78 69  ecifies the maxi
18b10 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74 68 65 20  mum size of the 
18b20 63 72 65 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a  created heap..**
18b30 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
18b40 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a  FIG_PCACHE_HDRSZ
18b50 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
18b60 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
18b70 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65  DRSZ.** <dd>^The
18b80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
18b90 43 41 43 48 45 5f 48 44 52 53 5a 20 6f 70 74 69  CACHE_HDRSZ opti
18ba0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
18bb0 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63  e parameter whic
18bc0 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65  h.** is a pointe
18bd0 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
18be0 61 6e 64 20 77 72 69 74 65 73 20 69 6e 74 6f 20  and writes into 
18bf0 74 68 61 74 20 69 6e 74 65 67 65 72 20 74 68 65  that integer the
18c00 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61   number of extra
18c10 0a 2a 2a 20 62 79 74 65 73 20 70 65 72 20 70 61  .** bytes per pa
18c20 67 65 20 72 65 71 75 69 72 65 64 20 66 6f 72 20  ge required for 
18c30 65 61 63 68 20 70 61 67 65 20 69 6e 20 5b 53 51  each page in [SQ
18c40 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
18c50 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 61  CACHE]..** The a
18c60 6d 6f 75 6e 74 20 6f 66 20 65 78 74 72 61 20 73  mount of extra s
18c70 70 61 63 65 20 72 65 71 75 69 72 65 64 20 63 61  pace required ca
18c80 6e 20 63 68 61 6e 67 65 20 64 65 70 65 6e 64 69  n change dependi
18c90 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c  ng on the compil
18ca0 65 72 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c  er,.** target pl
18cb0 61 74 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69  atform, and SQLi
18cc0 74 65 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  te version..**.*
18cd0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
18ce0 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74  G_PMASZ]].** <dt
18cf0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
18d00 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65  MASZ.** <dd>^The
18d10 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
18d20 4d 41 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65  MASZ option take
18d30 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d  s a single param
18d40 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  eter which.** is
18d50 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 69 6e 74   an unsigned int
18d60 65 67 65 72 20 61 6e 64 20 73 65 74 73 20 74 68  eger and sets th
18d70 65 20 22 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 53  e "Minimum PMA S
18d80 69 7a 65 22 20 66 6f 72 20 74 68 65 20 6d 75 6c  ize" for the mul
18d90 74 69 74 68 72 65 61 64 65 64 0a 2a 2a 20 73 6f  tithreaded.** so
18da0 72 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e 74  rter to that int
18db0 65 67 65 72 2e 20 20 54 68 65 20 64 65 66 61 75  eger.  The defau
18dc0 6c 74 20 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 53  lt minimum PMA S
18dd0 69 7a 65 20 69 73 20 73 65 74 20 62 79 20 74 68  ize is set by th
18de0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 52  e.** [SQLITE_SOR
18df0 54 45 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 69  TER_PMASZ] compi
18e00 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20  le-time option. 
18e10 20 4e 65 77 20 74 68 72 65 61 64 73 20 61 72 65   New threads are
18e20 20 6c 61 75 6e 63 68 65 64 0a 2a 2a 20 74 6f 20   launched.** to 
18e30 68 65 6c 70 20 77 69 74 68 20 73 6f 72 74 20 6f  help with sort o
18e40 70 65 72 61 74 69 6f 6e 73 20 77 68 65 6e 20 6d  perations when m
18e50 75 6c 74 69 74 68 72 65 61 64 65 64 20 73 6f 72  ultithreaded sor
18e60 74 69 6e 67 0a 2a 2a 20 69 73 20 65 6e 61 62 6c  ting.** is enabl
18e70 65 64 20 28 75 73 69 6e 67 20 74 68 65 20 5b 50  ed (using the [P
18e80 52 41 47 4d 41 20 74 68 72 65 61 64 73 5d 20 63  RAGMA threads] c
18e90 6f 6d 6d 61 6e 64 29 20 61 6e 64 20 74 68 65 20  ommand) and the 
18ea0 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 6e  amount of conten
18eb0 74 0a 2a 2a 20 74 6f 20 62 65 20 73 6f 72 74 65  t.** to be sorte
18ec0 64 20 65 78 63 65 65 64 73 20 74 68 65 20 70 61  d exceeds the pa
18ed0 67 65 20 73 69 7a 65 20 74 69 6d 65 73 20 74 68  ge size times th
18ee0 65 20 6d 69 6e 69 6d 75 6d 20 6f 66 20 74 68 65  e minimum of the
18ef0 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 63 61 63 68  .** [PRAGMA cach
18f00 65 5f 73 69 7a 65 5d 20 73 65 74 74 69 6e 67 20  e_size] setting 
18f10 61 6e 64 20 74 68 69 73 20 76 61 6c 75 65 2e 0a  and this value..
18f20 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
18f30 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53  ONFIG_STMTJRNL_S
18f40 50 49 4c 4c 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  PILL]].** <dt>SQ
18f50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54  LITE_CONFIG_STMT
18f60 4a 52 4e 4c 5f 53 50 49 4c 4c 0a 2a 2a 20 3c 64  JRNL_SPILL.** <d
18f70 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
18f80 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50  NFIG_STMTJRNL_SP
18f90 49 4c 4c 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  ILL option takes
18fa0 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65   a single parame
18fb0 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 62 65 63  ter which.** bec
18fc0 6f 6d 65 73 20 74 68 65 20 5b 73 74 61 74 65 6d  omes the [statem
18fd0 65 6e 74 20 6a 6f 75 72 6e 61 6c 5d 20 73 70 69  ent journal] spi
18fe0 6c 6c 2d 74 6f 2d 64 69 73 6b 20 74 68 72 65 73  ll-to-disk thres
18ff0 68 6f 6c 64 2e 20 20 0a 2a 2a 20 5b 53 74 61 74  hold.  .** [Stat
19000 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 5d 20  ement journals] 
19010 61 72 65 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f  are held in memo
19020 72 79 20 75 6e 74 69 6c 20 74 68 65 69 72 20 73  ry until their s
19030 69 7a 65 20 28 69 6e 20 62 79 74 65 73 29 0a 2a  ize (in bytes).*
19040 2a 20 65 78 63 65 65 64 73 20 74 68 69 73 20 74  * exceeds this t
19050 68 72 65 73 68 6f 6c 64 2c 20 61 74 20 77 68 69  hreshold, at whi
19060 63 68 20 70 6f 69 6e 74 20 74 68 65 79 20 61 72  ch point they ar
19070 65 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  e written to dis
19080 6b 2e 0a 2a 2a 20 4f 72 20 69 66 20 74 68 65 20  k..** Or if the 
19090 74 68 72 65 73 68 6f 6c 64 20 69 73 20 2d 31 2c  threshold is -1,
190a0 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e   statement journ
190b0 61 6c 73 20 61 72 65 20 61 6c 77 61 79 73 20 68  als are always h
190c0 65 6c 64 0a 2a 2a 20 65 78 63 6c 75 73 69 76 65  eld.** exclusive
190d0 6c 79 20 69 6e 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  ly in memory..**
190e0 20 53 69 6e 63 65 20 6d 61 6e 79 20 73 74 61 74   Since many stat
190f0 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 6e  ement journals n
19100 65 76 65 72 20 62 65 63 6f 6d 65 20 6c 61 72 67  ever become larg
19110 65 2c 20 73 65 74 74 69 6e 67 20 74 68 65 20 73  e, setting the s
19120 70 69 6c 6c 0a 2a 2a 20 74 68 72 65 73 68 6f 6c  pill.** threshol
19130 64 20 74 6f 20 61 20 76 61 6c 75 65 20 73 75 63  d to a value suc
19140 68 20 61 73 20 36 34 4b 69 42 20 63 61 6e 20 67  h as 64KiB can g
19150 72 65 61 74 6c 79 20 72 65 64 75 63 65 20 74 68  reatly reduce th
19160 65 20 61 6d 6f 75 6e 74 20 6f 66 0a 2a 2a 20 49  e amount of.** I
19170 2f 4f 20 72 65 71 75 69 72 65 64 20 74 6f 20 73  /O required to s
19180 75 70 70 6f 72 74 20 73 74 61 74 65 6d 65 6e 74  upport statement
19190 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68   rollback..** Th
191a0 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  e default value 
191b0 66 6f 72 20 74 68 69 73 20 73 65 74 74 69 6e 67  for this setting
191c0 20 69 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62   is controlled b
191d0 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  y the.** [SQLITE
191e0 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d  _STMTJRNL_SPILL]
191f0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
19200 74 69 6f 6e 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  tion..** </dl>.*
19210 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19220 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
19230 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20  READ  1  /* nil 
19240 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19250 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
19260 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c  READ   2  /* nil
19270 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19280 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
19290 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69  IZED    3  /* ni
192a0 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
192b0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
192c0 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73  C        4  /* s
192d0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
192e0 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
192f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
19300 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a  MALLOC     5  /*
19310 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
19320 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
19330 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
19340 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20  CRATCH       6  
19350 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
19360 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
19370 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
19380 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37  _PAGECACHE     7
19390 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
193a0 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65  sz, int N */.#de
193b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
193c0 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20  IG_HEAP         
193d0 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   8  /* void*, in
193e0 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e  t nByte, int min
193f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19400 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
19410 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f  TUS     9  /* bo
19420 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  olean */.#define
19430 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
19440 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20  UTEX        10  
19450 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
19460 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
19470 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
19480 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20  IG_GETMUTEX     
19490 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  11  /* sqlite3_m
194a0 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
194b0 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53  ./* previously S
194c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55  QLITE_CONFIG_CHU
194d0 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68  NKALLOC 12 which
194e0 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20   is now unused. 
194f0 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  */ .#define SQLI
19500 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
19510 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e  IDE    13  /* in
19520 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  t int */.#define
19530 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
19540 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20  CACHE       14  
19550 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66  /* no-op */.#def
19560 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
19570 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31  G_GETPCACHE    1
19580 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23  5  /* no-op */.#
19590 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
195a0 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20  NFIG_LOG        
195b0 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20    16  /* xFunc, 
195c0 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
195d0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55   SQLITE_CONFIG_U
195e0 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20  RI          17  
195f0 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  /* int */.#defin
19600 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
19610 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20  PCACHE2      18 
19620 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
19630 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a  he_methods2* */.
19640 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
19650 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
19660 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65     19  /* sqlite
19670 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
19680 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  2* */.#define SQ
19690 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
196a0 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20  RING_INDEX_SCAN 
196b0 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64  20  /* int */.#d
196c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
196d0 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20  FIG_SQLLOG      
196e0 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c   21  /* xSqllog,
196f0 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e   void* */.#defin
19700 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
19710 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20  MMAP_SIZE    22 
19720 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36   /* sqlite3_int6
19730 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  4, sqlite3_int64
19740 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19750 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
19760 48 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33  HEAPSIZE      23
19770 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a    /* int nByte *
19780 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19790 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
197a0 44 52 53 5a 20 20 20 20 20 20 20 20 32 34 20 20  DRSZ        24  
197b0 2f 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23  /* int *psz */.#
197c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
197d0 4e 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20  NFIG_PMASZ      
197e0 20 20 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20           25  /* 
197f0 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50  unsigned int szP
19800 6d 61 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ma */.#define SQ
19810 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54  LITE_CONFIG_STMT
19820 4a 52 4e 4c 5f 53 50 49 4c 4c 20 20 20 20 20 20  JRNL_SPILL      
19830 32 36 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65  26  /* int nByte
19840 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
19850 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
19860 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75  nnection Configu
19870 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a  ration Options.*
19880 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
19890 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
198a0 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
198b0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
198c0 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
198d0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
198e0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
198f0 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
19900 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
19910 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
19920 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
19930 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
19940 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
19950 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
19960 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
19970 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
19980 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
19990 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
199a0 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
199b0 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
199c0 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
199d0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
199e0 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73  fig()] to make s
199f0 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ure that.** the 
19a00 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54  call worked.  ^T
19a10 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
19a20 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
19a30 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
19a40 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
19a50 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
19a60 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
19a70 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
19a80 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
19a90 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
19aa0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
19ab0 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
19ac0 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
19ad0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
19ae0 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65  tion takes three
19af0 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
19b00 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
19b10 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f  mine the .** [lo
19b20 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
19b30 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67  llocator] config
19b40 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20  uration for the 
19b50 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
19b60 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66  tion]..** ^The f
19b70 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74  irst argument (t
19b80 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
19b90 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  er to [sqlite3_d
19ba0 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61  b_config()] is a
19bb0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
19bc0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
19bd0 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73  o use for lookas
19be0 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e  ide memory..** ^
19bf0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
19c00 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c  nt after the SQL
19c10 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
19c20 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d  KASIDE verb.** m
19c30 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68  ay be NULL in wh
19c40 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20  ich case SQLite 
19c50 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68  will allocate th
19c60 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62  e.** lookaside b
19c70 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69  uffer itself usi
19c80 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ng [sqlite3_mall
19c90 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f  oc()]. ^The seco
19ca0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
19cb0 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
19cc0 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
19cd0 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20  fer slot.  ^The 
19ce0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
19cf0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
19d00 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73  ** slots.  The s
19d10 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
19d20 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  r in the first a
19d30 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
19d40 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20  greater than.** 
19d50 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  or equal to the 
19d60 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73  product of the s
19d70 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20  econd and third 
19d80 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20  arguments.  The 
19d90 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62  buffer.** must b
19da0 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
19db0 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e  8-byte boundary.
19dc0 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64    ^If the second
19dd0 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
19de0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
19df0 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74  LOOKASIDE is not
19e00 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38   a multiple of 8
19e10 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c  , it is internal
19e20 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f  ly.** rounded do
19e30 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73  wn to the next s
19e40 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20  maller multiple 
19e50 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f  of 8.  ^(The loo
19e60 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a  kaside memory.**
19e70 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
19e80 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  or a database co
19e90 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c  nnection can onl
19ea0 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65  y be changed whe
19eb0 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63  n that.** connec
19ec0 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72  tion is not curr
19ed0 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b  ently using look
19ee0 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72  aside memory, or
19ef0 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a   in other words.
19f00 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72  ** when the "cur
19f10 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75  rent value" retu
19f20 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
19f30 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44  te3_db_status](D
19f40 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ,[SQLITE_CONFIG_
19f50 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20  LOOKASIDE],...) 
19f60 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20  is zero..** Any 
19f70 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67  attempt to chang
19f80 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  e the lookaside 
19f90 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61  memory configura
19fa0 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73  tion when lookas
19fb0 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73  ide.** memory is
19fc0 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74   in use leaves t
19fd0 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
19fe0 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72   unchanged and r
19ff0 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49  eturns .** [SQLI
1a000 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e  TE_BUSY].)^</dd>
1a010 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
1a020 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
1a030 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c  E_FKEY</dt>.** <
1a040 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
1a050 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
1a060 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  le or disable th
1a070 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66  e enforcement of
1a080 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79  .** [foreign key
1a090 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20   constraints].  
1a0a0 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
1a0b0 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
1a0c0 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
1a0d0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
1a0e0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
1a0f0 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
1a100 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ble FK enforceme
1a110 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20  nt,.** positive 
1a120 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66  to enable FK enf
1a130 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61  orcement or nega
1a140 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b  tive to leave FK
1a150 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20   enforcement.** 
1a160 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20  unchanged.  The 
1a170 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1a180 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
1a190 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
1a1a0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
1a1b0 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
1a1c0 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
1a1d0 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69  FK enforcement i
1a1e0 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66  s off or on.** f
1a1f0 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
1a200 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
1a210 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
1a220 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
1a230 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73   in.** which cas
1a240 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65  e the FK enforce
1a250 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20  ment setting is 
1a260 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
1a270 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  k. </dd>.**.** <
1a280 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
1a290 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45  IG_ENABLE_TRIGGE
1a2a0 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  R</dt>.** <dd> ^
1a2b0 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
1a2c0 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
1a2d0 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45   disable [CREATE
1a2e0 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
1a2f0 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73  ers]..** There s
1a300 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
1a310 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
1a320 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
1a330 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69  argument is an i
1a340 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
1a350 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69  0 to disable tri
1a360 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69  ggers,.** positi
1a370 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69  ve to enable tri
1a380 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76  ggers or negativ
1a390 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73  e to leave the s
1a3a0 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64  etting unchanged
1a3b0 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
1a3c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
1a3d0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
1a3e0 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
1a3f0 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
1a400 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
1a410 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72   whether trigger
1a420 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f  s are disabled o
1a430 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c  r enabled.** fol
1a440 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
1a450 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
1a460 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
1a470 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
1a480 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
1a490 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74  the trigger sett
1a4a0 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
1a4b0 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
1a4c0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
1a4d0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
1a4e0 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 3c  _FTS3_TOKENIZER<
1a4f0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
1a500 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
1a510 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
1a520 69 73 61 62 6c 65 20 74 68 65 20 74 77 6f 2d 61  isable the two-a
1a530 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 65 72 73 69  rgument.** versi
1a540 6f 6e 20 6f 66 20 74 68 65 20 5b 66 74 73 33 5f  on of the [fts3_
1a550 74 6f 6b 65 6e 69 7a 65 72 28 29 5d 20 66 75 6e  tokenizer()] fun
1a560 63 74 69 6f 6e 20 77 68 69 63 68 20 69 73 20 70  ction which is p
1a570 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 46  art of the.** [F
1a580 54 53 33 5d 20 66 75 6c 6c 2d 74 65 78 74 20 73  TS3] full-text s
1a590 65 61 72 63 68 20 65 6e 67 69 6e 65 20 65 78 74  earch engine ext
1a5a0 65 6e 73 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65  ension..** There
1a5b0 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
1a5c0 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
1a5d0 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  nts..** The firs
1a5e0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  t argument is an
1a5f0 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
1a600 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 66  s 0 to disable f
1a610 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20  ts3_tokenizer() 
1a620 6f 72 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  or.** positive t
1a630 6f 20 65 6e 61 62 6c 65 20 66 74 73 33 5f 74 6f  o enable fts3_to
1a640 6b 65 6e 69 7a 65 72 28 29 20 6f 72 20 6e 65 67  kenizer() or neg
1a650 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74  ative to leave t
1a660 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e  he setting.** un
1a670 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20  changed..** The 
1a680 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1a690 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
1a6a0 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
1a6b0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
1a6c0 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
1a6d0 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
1a6e0 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 20 69  fts3_tokenizer i
1a6f0 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e  s disabled or en
1a700 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  abled.** followi
1a710 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
1a720 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1a730 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c  ter may be a NUL
1a740 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a  L pointer, in.**
1a750 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
1a760 6e 65 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e  new setting is n
1a770 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
1a780 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  . </dd>.**.** <d
1a790 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
1a7a0 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58  G_ENABLE_LOAD_EX
1a7b0 54 45 4e 53 49 4f 4e 3c 2f 64 74 3e 0a 2a 2a 20  TENSION</dt>.** 
1a7c0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
1a7d0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
1a7e0 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ble or disable t
1a7f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64  he [sqlite3_load
1a800 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a  _extension()].**
1a810 20 69 6e 74 65 72 66 61 63 65 20 69 6e 64 65 70   interface indep
1a820 65 6e 64 65 6e 74 6c 79 20 6f 66 20 74 68 65 20  endently of the 
1a830 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  [load_extension(
1a840 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  )] SQL function.
1a850 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
1a860 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74  _enable_load_ext
1a870 65 6e 73 69 6f 6e 28 29 5d 20 41 50 49 20 65 6e  ension()] API en
1a880 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
1a890 73 20 62 6f 74 68 20 74 68 65 0a 2a 2a 20 43 2d  s both the.** C-
1a8a0 41 50 49 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61  API [sqlite3_loa
1a8b0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 61  d_extension()] a
1a8c0 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nd the SQL funct
1a8d0 69 6f 6e 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73  ion [load_extens
1a8e0 69 6f 6e 28 29 5d 2e 0a 2a 2a 20 54 68 65 72 65  ion()]..** There
1a8f0 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
1a900 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
1a910 6e 74 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 65  nts..** When the
1a920 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
1a930 74 6f 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  to this interfac
1a940 65 20 69 73 20 31 2c 20 74 68 65 6e 20 6f 6e 6c  e is 1, then onl
1a950 79 20 74 68 65 20 43 2d 41 50 49 20 69 73 0a 2a  y the C-API is.*
1a960 2a 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 74 68  * enabled and th
1a970 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  e SQL function r
1a980 65 6d 61 69 6e 73 20 64 69 73 61 62 6c 65 64 2e  emains disabled.
1a990 20 20 49 66 20 74 68 65 20 66 69 72 73 74 20 61    If the first a
1a9a0 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68  rgument to.** th
1a9b0 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
1a9c0 30 2c 20 74 68 65 6e 20 62 6f 74 68 20 74 68 65  0, then both the
1a9d0 20 43 2d 41 50 49 20 61 6e 64 20 74 68 65 20 53   C-API and the S
1a9e0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20  QL function are 
1a9f0 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 20 49 66 20  disabled..** If 
1aa00 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
1aa10 6e 74 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 6e  nt is -1, then n
1aa20 6f 20 63 68 61 6e 67 65 73 20 61 72 65 20 6d 61  o changes are ma
1aa30 64 65 20 74 6f 20 73 74 61 74 65 20 6f 66 20 65  de to state of e
1aa40 69 74 68 65 72 20 74 68 65 0a 2a 2a 20 43 2d 41  ither the.** C-A
1aa50 50 49 20 6f 72 20 74 68 65 20 53 51 4c 20 66 75  PI or the SQL fu
1aa60 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 73  nction..** The s
1aa70 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1aa80 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
1aa90 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
1aaa0 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
1aab0 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
1aac0 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 5b  dicate whether [
1aad0 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
1aae0 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66  ension()] interf
1aaf0 61 63 65 0a 2a 2a 20 69 73 20 64 69 73 61 62 6c  ace.** is disabl
1ab00 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 20 66 6f  ed or enabled fo
1ab10 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
1ab20 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
1ab30 61 72 61 6d 65 74 65 72 20 6d 61 79 0a 2a 2a 20  arameter may.** 
1ab40 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
1ab50 72 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  r, in which case
1ab60 20 74 68 65 20 6e 65 77 20 73 65 74 74 69 6e 67   the new setting
1ab70 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
1ab80 20 62 61 63 6b 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a   back..** </dd>.
1ab90 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  **.** </dl>.*/.#
1aba0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
1abb0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
1abc0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 30 30               100
1abd0 31 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69  1 /* void* int i
1abe0 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
1abf0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
1ac00 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 20 20  ABLE_FKEY       
1ac10 20 20 20 20 31 30 30 32 20 2f 2a 20 69 6e 74 20      1002 /* int 
1ac20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
1ac30 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1ac40 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20 20  ENABLE_TRIGGER  
1ac50 20 20 20 20 20 20 31 30 30 33 20 2f 2a 20 69 6e        1003 /* in
1ac60 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
1ac70 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
1ac80 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f  G_ENABLE_FTS3_TO
1ac90 4b 45 4e 49 5a 45 52 20 31 30 30 34 20 2f 2a 20  KENIZER 1004 /* 
1aca0 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
1acb0 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
1acc0 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f  FIG_ENABLE_LOAD_
1acd0 45 58 54 45 4e 53 49 4f 4e 20 31 30 30 35 20 2f  EXTENSION 1005 /
1ace0 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a  * int int* */...
1acf0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1ad00 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c  Enable Or Disabl
1ad10 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c  e Extended Resul
1ad20 74 20 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f  t Codes.** METHO
1ad30 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1ad40 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
1ad50 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
1ad60 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e  des() routine en
1ad70 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
1ad80 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64  s the.** [extend
1ad90 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
1ada0 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69   feature of SQLi
1adb0 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65  te. ^The extende
1adc0 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65  d result.** code
1add0 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
1ade0 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69  y default for hi
1adf0 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69  storical compati
1ae00 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54  bility..*/.SQLIT
1ae10 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
1ae20 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
1ae30 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
1ae40 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c  _codes(sqlite3*,
1ae50 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a   int onoff);../*
1ae60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61  .** CAPI3REF: La
1ae70 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a  st Insert Rowid.
1ae80 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1ae90 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65  e3.**.** ^Each e
1aea0 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c  ntry in most SQL
1aeb0 69 74 65 20 74 61 62 6c 65 73 20 28 65 78 63 65  ite tables (exce
1aec0 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55 54 20  pt for [WITHOUT 
1aed0 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a  ROWID] tables).*
1aee0 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36  * has a unique 6
1aef0 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20  4-bit signed.** 
1af00 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c  integer key call
1af10 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20  ed the [ROWID | 
1af20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72  "rowid"]. ^The r
1af30 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61  owid is always a
1af40 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61  vailable.** as a
1af50 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c  n undeclared col
1af60 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c  umn named ROWID,
1af70 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f   OID, or _ROWID_
1af80 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73   as long as thos
1af90 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e  e.** names are n
1afa0 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20  ot also used by 
1afb0 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
1afc0 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66  red columns. ^If
1afd0 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61  .** the table ha
1afe0 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79  s a column of ty
1aff0 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d  pe [INTEGER PRIM
1b000 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68  ARY KEY] then th
1b010 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20  at column.** is 
1b020 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f  another alias fo
1b030 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a  r the rowid..**.
1b040 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1b050 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
1b060 64 28 44 29 20 69 6e 74 65 72 66 61 63 65 20 72  d(D) interface r
1b070 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69  eturns the [rowi
1b080 64 5d 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6d 6f  d] of the .** mo
1b090 73 74 20 72 65 63 65 6e 74 20 73 75 63 63 65 73  st recent succes
1b0a0 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e  sful [INSERT] in
1b0b0 74 6f 20 61 20 72 6f 77 69 64 20 74 61 62 6c 65  to a rowid table
1b0c0 20 6f 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62   or [virtual tab
1b0d0 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61  le].** on databa
1b0e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  se connection D.
1b0f0 0a 2a 2a 20 5e 49 6e 73 65 72 74 73 20 69 6e 74  .** ^Inserts int
1b100 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44  o [WITHOUT ROWID
1b110 5d 20 74 61 62 6c 65 73 20 61 72 65 20 6e 6f 74  ] tables are not
1b120 20 72 65 63 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49   recorded..** ^I
1b130 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20  f no successful 
1b140 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f 20 72  [INSERT]s into r
1b150 6f 77 69 64 20 74 61 62 6c 65 73 0a 2a 2a 20 68  owid tables.** h
1b160 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65  ave ever occurre
1b170 64 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  d on the databas
1b180 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20  e connection D, 
1b190 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33  .** then sqlite3
1b1a0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
1b1b0 69 64 28 44 29 20 72 65 74 75 72 6e 73 20 7a 65  id(D) returns ze
1b1c0 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61  ro..**.** ^(If a
1b1d0 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72  n [INSERT] occur
1b1e0 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  s within a trigg
1b1f0 65 72 20 6f 72 20 77 69 74 68 69 6e 20 61 20 5b  er or within a [
1b200 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a  virtual table].*
1b210 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74  * method, then t
1b220 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c  his routine will
1b230 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77   return the [row
1b240 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72  id] of the inser
1b250 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f  ted.** row as lo
1b260 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65  ng as the trigge
1b270 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62  r or virtual tab
1b280 6c 65 20 6d 65 74 68 6f 64 20 69 73 20 72 75 6e  le method is run
1b290 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63  ning..** But onc
1b2a0 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72  e the trigger or
1b2b0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d   virtual table m
1b2c0 65 74 68 6f 64 20 65 6e 64 73 2c 20 74 68 65 20  ethod ends, the 
1b2d0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a  value returned .
1b2e0 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 69  ** by this routi
1b2f0 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 77 68  ne reverts to wh
1b300 61 74 20 69 74 20 77 61 73 20 62 65 66 6f 72 65  at it was before
1b310 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20   the trigger or 
1b320 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65  virtual.** table
1b330 20 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e   method began.)^
1b340 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45  .**.** ^An [INSE
1b350 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64  RT] that fails d
1b360 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69  ue to a constrai
1b370 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20  nt violation is 
1b380 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73  not a.** success
1b390 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64  ful [INSERT] and
1b3a0 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
1b3b0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1b3c0 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72  ned by this.** r
1b3d0 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49  outine.  ^Thus I
1b3e0 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49  NSERT OR FAIL, I
1b3f0 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c  NSERT OR IGNORE,
1b400 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42   INSERT OR ROLLB
1b410 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45  ACK,.** and INSE
1b420 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65  RT OR ABORT make
1b430 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74   no changes to t
1b440 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
1b450 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  of this.** routi
1b460 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e  ne when their in
1b470 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20  sertion fails.  
1b480 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52  ^(When INSERT OR
1b490 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f   REPLACE.** enco
1b4a0 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61  unters a constra
1b4b0 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69  int violation, i
1b4c0 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e  t does not fail.
1b4d0 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20    The.** INSERT 
1b4e0 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d  continues to com
1b4f0 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65  pletion after de
1b500 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74  leting rows that
1b510 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63   caused.** the c
1b520 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65  onstraint proble
1b530 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52  m so INSERT OR R
1b540 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61  EPLACE will alwa
1b550 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65  ys change.** the
1b560 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
1b570 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
1b580 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68  )^.**.** ^For th
1b590 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68  e purposes of th
1b5a0 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b  is routine, an [
1b5b0 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69  INSERT] is consi
1b5c0 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73  dered to.** be s
1b5d0 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69  uccessful even i
1b5e0 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65  f it is subseque
1b5f0 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ntly rolled back
1b600 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  ..**.** This fun
1b610 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69  ction is accessi
1b620 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65  ble to SQL state
1b630 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a  ments via the.**
1b640 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f   [last_insert_ro
1b650 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69  wid() SQL functi
1b660 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
1b670 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
1b680 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b  performs a new [
1b690 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73  INSERT] on the s
1b6a0 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  ame.** database 
1b6b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65  connection while
1b6c0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61   the [sqlite3_la
1b6d0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1b6e0 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  )].** function i
1b6f0 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68  s running and th
1b700 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c  us changes the l
1b710 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69  ast insert [rowi
1b720 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  d],.** then the 
1b730 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
1b740 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  y [sqlite3_last_
1b750 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20  insert_rowid()] 
1b760 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61  is.** unpredicta
1b770 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f  ble and might no
1b780 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74  t equal either t
1b790 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65  he old or the ne
1b7a0 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74  w.** last insert
1b7b0 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c   [rowid]..*/.SQL
1b7c0 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
1b7d0 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 54 44  int64 SQLITE_STD
1b7e0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6c 61 73  CALL sqlite3_las
1b7f0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73  t_insert_rowid(s
1b800 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
1b810 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74   CAPI3REF: Count
1b820 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52   The Number Of R
1b830 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20  ows Modified.** 
1b840 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1b850 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
1b860 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
1b870 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
1b880 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 72 74  modified, insert
1b890 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64  ed or.** deleted
1b8a0 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63   by the most rec
1b8b0 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
1b8c0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
1b8d0 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74  r DELETE.** stat
1b8e0 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 64 61 74  ement on the dat
1b8f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1b900 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
1b910 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
1b920 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69 6e 67 20  ..** ^Executing 
1b930 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f  any other type o
1b940 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  f SQL statement 
1b950 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20  does not modify 
1b960 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  the value.** ret
1b970 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 75  urned by this fu
1b980 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  nction..**.** ^O
1b990 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65  nly changes made
1b9a0 20 64 69 72 65 63 74 6c 79 20 62 79 20 74 68 65   directly by the
1b9b0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
1b9c0 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
1b9d0 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69  ent are.** consi
1b9e0 64 65 72 65 64 20 2d 20 61 75 78 69 6c 69 61 72  dered - auxiliar
1b9f0 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  y changes caused
1ba00 20 62 79 20 5b 43 52 45 41 54 45 20 54 52 49 47   by [CREATE TRIG
1ba10 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2c  GER | triggers],
1ba20 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65   .** [foreign ke
1ba30 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52  y actions] or [R
1ba40 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69  EPLACE] constrai
1ba50 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72  nt resolution ar
1ba60 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a  e not counted..*
1ba70 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f  * .** Changes to
1ba80 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65   a view that are
1ba90 20 69 6e 74 65 72 63 65 70 74 65 64 20 62 79 20   intercepted by 
1baa0 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20 4f 46 20  .** [INSTEAD OF 
1bab0 74 72 69 67 67 65 72 20 7c 20 49 4e 53 54 45 41  trigger | INSTEA
1bac0 44 20 4f 46 20 74 72 69 67 67 65 72 73 5d 20 61  D OF triggers] a
1bad0 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20  re not counted. 
1bae0 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72  ^The value .** r
1baf0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1bb00 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6d 6d  e3_changes() imm
1bb10 65 64 69 61 74 65 6c 79 20 61 66 74 65 72 20 61  ediately after a
1bb20 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  n INSERT, UPDATE
1bb30 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73   or .** DELETE s
1bb40 74 61 74 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20  tatement run on 
1bb50 61 20 76 69 65 77 20 69 73 20 61 6c 77 61 79 73  a view is always
1bb60 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e   zero. Only chan
1bb70 67 65 73 20 6d 61 64 65 20 74 6f 20 72 65 61 6c  ges made to real
1bb80 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61 72 65 20   .** tables are 
1bb90 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  counted..**.** T
1bba0 68 69 6e 67 73 20 61 72 65 20 6d 6f 72 65 20 63  hings are more c
1bbb0 6f 6d 70 6c 69 63 61 74 65 64 20 69 66 20 74 68  omplicated if th
1bbc0 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
1bbd0 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a  s() function is.
1bbe0 2a 2a 20 65 78 65 63 75 74 65 64 20 77 68 69 6c  ** executed whil
1bbf0 65 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67  e a trigger prog
1bc00 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20  ram is running. 
1bc10 54 68 69 73 20 6d 61 79 20 68 61 70 70 65 6e 20  This may happen 
1bc20 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61  if the.** progra
1bc30 6d 20 75 73 65 73 20 74 68 65 20 5b 63 68 61 6e  m uses the [chan
1bc40 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
1bc50 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20  on], or if some 
1bc60 6f 74 68 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  other callback.*
1bc70 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b  * function invok
1bc80 65 73 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  es sqlite3_chang
1bc90 65 73 28 29 20 64 69 72 65 63 74 6c 79 2e 20 45  es() directly. E
1bca0 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a  ssentially:.** .
1bcb0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69  ** <ul>.**   <li
1bcc0 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e 74 65 72  > ^(Before enter
1bcd0 69 6e 67 20 61 20 74 72 69 67 67 65 72 20 70 72  ing a trigger pr
1bce0 6f 67 72 61 6d 20 74 68 65 20 76 61 6c 75 65 20  ogram the value 
1bcf0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20  returned by.**  
1bd00 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 68        sqlite3_ch
1bd10 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e  anges() function
1bd20 20 69 73 20 73 61 76 65 64 2e 20 41 66 74 65 72   is saved. After
1bd30 20 74 68 65 20 74 72 69 67 67 65 72 20 70 72 6f   the trigger pro
1bd40 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20  gram .**        
1bd50 68 61 73 20 66 69 6e 69 73 68 65 64 2c 20 74 68  has finished, th
1bd60 65 20 6f 72 69 67 69 6e 61 6c 20 76 61 6c 75 65  e original value
1bd70 20 69 73 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a   is restored.)^.
1bd80 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28  ** .**   <li> ^(
1bd90 57 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  Within a trigger
1bda0 20 70 72 6f 67 72 61 6d 20 65 61 63 68 20 49 4e   program each IN
1bdb0 53 45 52 54 2c 20 55 50 44 41 54 45 20 61 6e 64  SERT, UPDATE and
1bdc0 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20   DELETE .**     
1bdd0 20 20 20 73 74 61 74 65 6d 65 6e 74 20 73 65 74     statement set
1bde0 73 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  s the value retu
1bdf0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
1be00 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20  changes() .**   
1be10 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65       upon comple
1be20 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20  tion as normal. 
1be30 4f 66 20 63 6f 75 72 73 65 2c 20 74 68 69 73 20  Of course, this 
1be40 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69  value will not i
1be50 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20 20 20 20  nclude .**      
1be60 20 20 61 6e 79 20 63 68 61 6e 67 65 73 20 70 65    any changes pe
1be70 72 66 6f 72 6d 65 64 20 62 79 20 73 75 62 2d 74  rformed by sub-t
1be80 72 69 67 67 65 72 73 2c 20 61 73 20 74 68 65 20  riggers, as the 
1be90 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1bea0 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 76 61 6c  ) .**        val
1beb0 75 65 20 77 69 6c 6c 20 62 65 20 73 61 76 65 64  ue will be saved
1bec0 20 61 6e 64 20 72 65 73 74 6f 72 65 64 20 61 66   and restored af
1bed0 74 65 72 20 65 61 63 68 20 73 75 62 2d 74 72 69  ter each sub-tri
1bee0 67 67 65 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a  gger has run.)^.
1bef0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20  ** </ul>.** .** 
1bf00 5e 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74  ^This means that
1bf10 20 69 66 20 74 68 65 20 63 68 61 6e 67 65 73 28   if the changes(
1bf20 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28  ) SQL function (
1bf30 6f 72 20 73 69 6d 69 6c 61 72 29 20 69 73 20 75  or similar) is u
1bf40 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69  sed.** by the fi
1bf50 72 73 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  rst INSERT, UPDA
1bf60 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  TE or DELETE sta
1bf70 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20  tement within a 
1bf80 74 72 69 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20  trigger, it .** 
1bf90 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
1bfa0 65 20 61 73 20 73 65 74 20 77 68 65 6e 20 74 68  e as set when th
1bfb0 65 20 63 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d  e calling statem
1bfc0 65 6e 74 20 62 65 67 61 6e 20 65 78 65 63 75 74  ent began execut
1bfd0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69  ing..** ^If it i
1bfe0 73 20 75 73 65 64 20 62 79 20 74 68 65 20 73 65  s used by the se
1bff0 63 6f 6e 64 20 6f 72 20 73 75 62 73 65 71 75 65  cond or subseque
1c000 6e 74 20 73 75 63 68 20 73 74 61 74 65 6d 65 6e  nt such statemen
1c010 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  t within a trigg
1c020 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20  er .** program, 
1c030 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
1c040 65 64 20 72 65 66 6c 65 63 74 73 20 74 68 65 20  ed reflects the 
1c050 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d  number of rows m
1c060 6f 64 69 66 69 65 64 20 62 79 20 74 68 65 20 0a  odified by the .
1c070 2a 2a 20 70 72 65 76 69 6f 75 73 20 49 4e 53 45  ** previous INSE
1c080 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
1c090 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77  LETE statement w
1c0a0 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 74  ithin the same t
1c0b0 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65  rigger..**.** Se
1c0c0 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
1c0d0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
1c0e0 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
1c0f0 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
1c100 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
1c110 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28  nd the [changes(
1c120 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
1c130 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
1c140 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
1c150 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
1c160 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
1c170 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
1c180 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  le [sqlite3_chan
1c190 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
1c1a0 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
1c1b0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20   returned.** is 
1c1c0 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
1c1d0 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
1c1e0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
1c1f0 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
1c200 4c 4c 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  LL sqlite3_chang
1c210 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
1c220 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1c230 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52  otal Number Of R
1c240 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20  ows Modified.** 
1c250 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1c260 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
1c270 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
1c280 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66   total number of
1c290 20 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20   rows inserted, 
1c2a0 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64  modified or.** d
1c2b0 65 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49  eleted by all [I
1c2c0 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d  NSERT], [UPDATE]
1c2d0 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61   or [DELETE] sta
1c2e0 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65  tements complete
1c2f0 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64  d.** since the d
1c300 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1c310 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69  on was opened, i
1c320 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65  ncluding those e
1c330 78 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61  xecuted as.** pa
1c340 72 74 20 6f 66 20 74 72 69 67 67 65 72 20 70 72  rt of trigger pr
1c350 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69  ograms. ^Executi
1c360 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70  ng any other typ
1c370 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65  e of SQL stateme
1c380 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61  nt.** does not a
1c390 66 66 65 63 74 20 74 68 65 20 76 61 6c 75 65 20  ffect the value 
1c3a0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1c3b0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
1c3c0 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61  s()..** .** ^Cha
1c3d0 6e 67 65 73 20 6d 61 64 65 20 61 73 20 70 61 72  nges made as par
1c3e0 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65  t of [foreign ke
1c3f0 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69  y actions] are i
1c400 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a  ncluded in the.*
1c410 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f  * count, but tho
1c420 73 65 20 6d 61 64 65 20 61 73 20 70 61 72 74 20  se made as part 
1c430 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74  of REPLACE const
1c440 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e  raint resolution
1c450 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68   are.** not. ^Ch
1c460 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20  anges to a view 
1c470 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65  that are interce
1c480 70 74 65 64 20 62 79 20 49 4e 53 54 45 41 44 20  pted by INSTEAD 
1c490 4f 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20  OF triggers .** 
1c4a0 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
1c4b0 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  .** .** See also
1c4c0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68   the [sqlite3_ch
1c4d0 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
1c4e0 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
1c4f0 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
1c500 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61  ], and the [tota
1c510 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  l_changes() SQL 
1c520 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
1c530 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
1c540 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
1c550 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
1c560 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1c570 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
1c580 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
1c590 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
1c5a0 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
1c5b0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20  .** returned is 
1c5c0 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
1c5d0 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
1c5e0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
1c5f0 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
1c600 4c 4c 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  LL sqlite3_total
1c610 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
1c620 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1c630 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41  REF: Interrupt A
1c640 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75   Long-Running Qu
1c650 65 72 79 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ery.** METHOD: s
1c660 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
1c670 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73  is function caus
1c680 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64  es any pending d
1c690 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
1c6a0 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a  n to abort and.*
1c6b0 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20  * return at its 
1c6c0 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75  earliest opportu
1c6d0 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69  nity. This routi
1c6e0 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a  ne is typically.
1c6f0 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73  ** called in res
1c700 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20  ponse to a user 
1c710 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70  action such as p
1c720 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22  ressing "Cancel"
1c730 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68  .** or Ctrl-C wh
1c740 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e  ere the user wan
1c750 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20  ts a long query 
1c760 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c  operation to hal
1c770 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79  t.** immediately
1c780 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73  ..**.** ^It is s
1c790 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
1c7a0 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20   routine from a 
1c7b0 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74  thread different
1c7c0 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72   from the.** thr
1c7d0 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72  ead that is curr
1c7e0 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68  ently running th
1c7f0 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  e database opera
1c800 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a  tion.  But it.**
1c810 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
1c820 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
1c830 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  e with a [databa
1c840 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
1c850 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64  hat.** is closed
1c860 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20   or might close 
1c870 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69  before sqlite3_i
1c880 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72  nterrupt() retur
1c890 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ns..**.** ^If an
1c8a0 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
1c8b0 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69  s very nearly fi
1c8c0 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69  nished at the ti
1c8d0 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  me when.** sqlit
1c8e0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69  e3_interrupt() i
1c8f0 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69  s called, then i
1c900 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65  t might not have
1c910 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a   an opportunity.
1c920 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75  ** to be interru
1c930 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63  pted and might c
1c940 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c  ontinue to compl
1c950 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  etion..**.** ^An
1c960 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74   SQL operation t
1c970 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74  hat is interrupt
1c980 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ed will return [
1c990 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
1c9a0 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e  ]..** ^If the in
1c9b0 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70  terrupted SQL op
1c9c0 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e  eration is an IN
1c9d0 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
1c9e0 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20   DELETE.** that 
1c9f0 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70  is inside an exp
1ca00 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
1ca10 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69  n, then the enti
1ca20 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a  re transaction.*
1ca30 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64  * will be rolled
1ca40 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
1ca50 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  lly..**.** ^The 
1ca60 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1ca70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20  t(D) call is in 
1ca80 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c  effect until all
1ca90 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
1caa0 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ng.** SQL statem
1cab0 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  ents on [databas
1cac0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
1cad0 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20  complete.  ^Any 
1cae0 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  new SQL statemen
1caf0 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
1cb00 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
1cb10 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1cb20 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65  pt() call and be
1cb30 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e  fore the .** run
1cb40 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20  ning statements 
1cb50 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65  reaches zero are
1cb60 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20   interrupted as 
1cb70 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e  if they had been
1cb80 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f  .** running prio
1cb90 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
1cba0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
1cbb0 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61  l.  ^New SQL sta
1cbc0 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
1cbd0 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
1cbe0 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74  r the running st
1cbf0 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65  atement count re
1cc00 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a  aches zero are.*
1cc10 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62  * not effected b
1cc20 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  y the sqlite3_in
1cc30 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41  terrupt()..** ^A
1cc40 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
1cc50 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 68  _interrupt(D) th
1cc60 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74  at occurs when t
1cc70 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e  here are no runn
1cc80 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
1cc90 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70  ments is a no-op
1cca0 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65   and has no effe
1ccb0 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d  ct on SQL statem
1ccc0 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
1ccd0 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
1cce0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
1ccf0 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75  rupt() call retu
1cd00 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  rns..**.** If th
1cd10 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1cd20 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69  ction closes whi
1cd30 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  le [sqlite3_inte
1cd40 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72  rrupt()].** is r
1cd50 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20  unning then bad 
1cd60 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65  things will like
1cd70 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51  ly happen..*/.SQ
1cd80 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51  LITE_API void SQ
1cd90 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
1cda0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73  ite3_interrupt(s
1cdb0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
1cdc0 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
1cdd0 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53  mine If An SQL S
1cde0 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70  tatement Is Comp
1cdf0 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  lete.**.** These
1ce00 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
1ce10 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d  eful during comm
1ce20 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74  and-line input t
1ce30 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74  o determine if t
1ce40 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20  he.** currently 
1ce50 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65  entered text see
1ce60 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d  ms to form a com
1ce70 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d  plete SQL statem
1ce80 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64  ent or.** if add
1ce90 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73  itional input is
1cea0 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73   needed before s
1ceb0 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20  ending the text 
1cec0 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66  into.** SQLite f
1ced0 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68  or parsing.  ^Th
1cee0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
1cef0 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70  urn 1 if the inp
1cf00 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70  ut string.** app
1cf10 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d  ears to be a com
1cf20 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d  plete SQL statem
1cf30 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65  ent.  ^A stateme
1cf40 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20  nt is judged to 
1cf50 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69  be.** complete i
1cf60 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61  f it ends with a
1cf70 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e   semicolon token
1cf80 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72   and is not a pr
1cf90 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c  efix of a.** wel
1cfa0 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20  l-formed CREATE 
1cfb0 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e  TRIGGER statemen
1cfc0 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20  t.  ^Semicolons 
1cfd0 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65  that are embedde
1cfe0 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69  d within.** stri
1cff0 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71  ng literals or q
1d000 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72  uoted identifier
1d010 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e   names or commen
1d020 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e  ts are not.** in
1d030 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73  dependent tokens
1d040 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20   (they are part 
1d050 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20  of the token in 
1d060 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a  which they are.*
1d070 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20  * embedded) and 
1d080 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e  thus do not coun
1d090 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74  t as a statement
1d0a0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57   terminator.  ^W
1d0b0 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64  hitespace.** and
1d0c0 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66   comments that f
1d0d0 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20  ollow the final 
1d0e0 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67  semicolon are ig
1d0f0 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  nored..**.** ^Th
1d100 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
1d110 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61  urn 0 if the sta
1d120 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70  tement is incomp
1d130 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20  lete.  ^If a.** 
1d140 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1d150 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51  n fails, then SQ
1d160 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65  LITE_NOMEM is re
1d170 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
1d180 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f  hese routines do
1d190 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53   not parse the S
1d1a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  QL statements th
1d1b0 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64  us.** will not d
1d1c0 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61  etect syntactica
1d1d0 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51  lly incorrect SQ
1d1e0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51  L..**.** ^(If SQ
1d1f0 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65  Lite has not bee
1d200 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73  n initialized us
1d210 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  ing [sqlite3_ini
1d220 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72  tialize()] prior
1d230 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67   .** to invoking
1d240 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
1d250 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74  e16() then sqlit
1d260 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
1d270 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75  is invoked.** au
1d280 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73  tomatically by s
1d290 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
1d2a0 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e  6().  If that in
1d2b0 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69  itialization fai
1d2c0 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ls,.** then the 
1d2d0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
1d2e0 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  m sqlite3_comple
1d2f0 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e  te16() will be n
1d300 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72  on-zero.** regar
1d310 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
1d320 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75   or not the inpu
1d330 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74  t SQL is complet
1d340 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  e.)^.**.** The i
1d350 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
1d360 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73  _complete()] mus
1d370 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t be a zero-term
1d380 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20  inated.** UTF-8 
1d390 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  string..**.** Th
1d3a0 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  e input to [sqli
1d3b0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
1d3c0 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f  ] must be a zero
1d3d0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
1d3e0 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20  TF-16 string in 
1d3f0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
1d400 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  r..*/.SQLITE_API
1d410 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
1d420 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  ALL sqlite3_comp
1d430 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20  lete(const char 
1d440 2a 73 71 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  *sql);.SQLITE_AP
1d450 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
1d460 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6d  CALL sqlite3_com
1d470 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f  plete16(const vo
1d480 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  id *sql);../*.**
1d490 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73   CAPI3REF: Regis
1d4a0 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54  ter A Callback T
1d4b0 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f  o Handle SQLITE_
1d4c0 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20 4b  BUSY Errors.** K
1d4d0 45 59 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d 68  EYWORDS: {busy-h
1d4e0 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 7d  andler callback}
1d4f0 20 7b 62 75 73 79 20 68 61 6e 64 6c 65 72 7d 0a   {busy handler}.
1d500 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1d510 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e3.**.** ^The sq
1d520 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1d530 65 72 28 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e  er(D,X,P) routin
1d540 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63  e sets a callbac
1d550 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20  k function X.** 
1d560 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e  that might be in
1d570 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d  voked with argum
1d580 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a  ent P whenever.*
1d590 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20  * an attempt is 
1d5a0 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 61  made to access a
1d5b0 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20   database table 
1d5c0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a  associated with.
1d5d0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1d5e0 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20  nection] D when 
1d5f0 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a  another thread.*
1d600 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73  * or process has
1d610 20 74 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65   the table locke
1d620 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  d..** The sqlite
1d630 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
1d640 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
1d650 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a  ed to implement.
1d660 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ** [sqlite3_busy
1d670 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20  _timeout()] and 
1d680 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d  [PRAGMA busy_tim
1d690 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  eout]..**.** ^If
1d6a0 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
1d6b0 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ck is NULL, then
1d6c0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
1d6d0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  * is returned im
1d6e0 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65  mediately upon e
1d6f0 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20  ncountering the 
1d700 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62  lock.  ^If the b
1d710 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  usy callback.** 
1d720 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65  is not NULL, the
1d730 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d  n the callback m
1d740 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
1d750 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e  with two argumen
1d760 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ts..**.** ^The f
1d770 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
1d780 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1d790 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  r is a copy of t
1d7a0 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  he void* pointer
1d7b0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65   which.** is the
1d7c0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
1d7d0 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  to sqlite3_busy_
1d7e0 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65  handler().  ^The
1d7f0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
1d800 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20   to.** the busy 
1d810 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
1d820 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
1d830 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65  f times that the
1d840 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61   busy handler ha
1d850 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65  s.** been invoke
1d860 64 20 70 72 65 76 69 6f 75 73 6c 79 20 66 6f 72  d previously for
1d870 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e   the same lockin
1d880 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
1d890 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61  e.** busy callba
1d8a0 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68  ck returns 0, th
1d8b0 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c  en no additional
1d8c0 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61   attempts are ma
1d8d0 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20  de to.** access 
1d8e0 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  the database and
1d8f0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69   [SQLITE_BUSY] i
1d900 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f  s returned.** to
1d910 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1d920 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c  ..** ^If the cal
1d930 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
1d940 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f  n-zero, then ano
1d950 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20  ther attempt.** 
1d960 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73  is made to acces
1d970 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  s the database a
1d980 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70  nd the cycle rep
1d990 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eats..**.** The 
1d9a0 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75  presence of a bu
1d9b0 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20  sy handler does 
1d9c0 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68  not guarantee th
1d9d0 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e  at it will be in
1d9e0 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68  voked.** when th
1d9f0 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74  ere is lock cont
1da00 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69  ention. ^If SQLi
1da10 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  te determines th
1da20 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  at invoking the 
1da30 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20  busy.** handler 
1da40 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20  could result in 
1da50 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77  a deadlock, it w
1da60 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64  ill go ahead and
1da70 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1da80 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20  BUSY].** to the 
1da90 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74  application inst
1daa0 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20  ead of invoking 
1dab0 74 68 65 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e  the .** busy han
1dac0 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65  dler..** Conside
1dad0 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65  r a scenario whe
1dae0 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69  re one process i
1daf0 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64  s holding a read
1db00 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74   lock that.** it
1db10 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72   is trying to pr
1db20 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72  omote to a reser
1db30 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20  ved lock and.** 
1db40 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  a second process
1db50 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
1db60 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74  served lock that
1db70 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a   it is trying.**
1db80 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
1db90 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b  n exclusive lock
1dba0 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f  .  The first pro
1dbb0 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63  cess cannot proc
1dbc0 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69  eed.** because i
1dbd0 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
1dbe0 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
1dbf0 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
1dc00 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63  s cannot.** proc
1dc10 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69  eed because it i
1dc20 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
1dc30 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68   first.  If both
1dc40 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e   processes.** in
1dc50 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61  voke the busy ha
1dc60 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20  ndlers, neither 
1dc70 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72  will make any pr
1dc80 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f  ogress.  Therefo
1dc90 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65  re,.** SQLite re
1dca0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55  turns [SQLITE_BU
1dcb0 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73  SY] for the firs
1dcc0 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e  t process, hopin
1dcd0 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77  g that this.** w
1dce0 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66  ill induce the f
1dcf0 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20  irst process to 
1dd00 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64  release its read
1dd10 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a   lock and allow.
1dd20 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  ** the second pr
1dd30 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64  ocess to proceed
1dd40 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ..**.** ^The def
1dd50 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61  ault busy callba
1dd60 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ck is NULL..**.*
1dd70 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e  * ^(There can on
1dd80 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
1dd90 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69  usy handler defi
1dda0 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  ned for each.** 
1ddb0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1ddc0 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20  tion].  Setting 
1ddd0 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c  a new busy handl
1dde0 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a  er clears any.**
1ddf0 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20   previously set 
1de00 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74  handler.)^  ^Not
1de10 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b  e that calling [
1de20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
1de30 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76  eout()].** or ev
1de40 61 6c 75 61 74 69 6e 67 20 5b 50 52 41 47 4d 41  aluating [PRAGMA
1de50 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d   busy_timeout=N]
1de60 20 77 69 6c 6c 20 63 68 61 6e 67 65 20 74 68 65   will change the
1de70 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72  .** busy handler
1de80 20 61 6e 64 20 74 68 75 73 20 63 6c 65 61 72 20   and thus clear 
1de90 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 73  any previously s
1dea0 65 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  et busy handler.
1deb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20  .**.** The busy 
1dec0 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20  callback should 
1ded0 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74  not take any act
1dee0 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66  ions which modif
1def0 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  y the.** databas
1df00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
1df10 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
1df20 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20  sy handler.  In 
1df30 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20  other words,.** 
1df40 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1df50 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e   is not reentran
1df60 74 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74  t.  Any such act
1df70 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69  ions.** result i
1df80 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
1df90 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62  vior..** .** A b
1dfa0 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74  usy handler must
1dfb0 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64   not close the d
1dfc0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1dfd0 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72  on.** or [prepar
1dfe0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
1dff0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
1e000 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a  usy handler..*/.
1e010 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
1e020 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
1e030 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1e040 65 72 28 73 71 6c 69 74 65 33 2a 2c 69 6e 74 28  er(sqlite3*,int(
1e050 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 76 6f  *)(void*,int),vo
1e060 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
1e070 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73  I3REF: Set A Bus
1e080 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54  y Timeout.** MET
1e090 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1e0a0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
1e0b0 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33   sets a [sqlite3
1e0c0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20  _busy_handler | 
1e0d0 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68  busy handler] th
1e0e0 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72  at sleeps.** for
1e0f0 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f   a specified amo
1e100 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e  unt of time when
1e110 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b   a table is lock
1e120 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65  ed.  ^The handle
1e130 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20  r.** will sleep 
1e140 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75  multiple times u
1e150 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d  ntil at least "m
1e160 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
1e170 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68  of sleeping.** h
1e180 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e  ave accumulated.
1e190 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73    ^After at leas
1e1a0 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
1e1b0 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c  nds of sleeping,
1e1c0 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20  .** the handler 
1e1d0 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20  returns 0 which 
1e1e0 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f  causes [sqlite3_
1e1f0 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72  step()] to retur
1e200 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53  n.** [SQLITE_BUS
1e210 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  Y]..**.** ^Calli
1e220 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ng this routine 
1e230 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74  with an argument
1e240 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
1e250 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74  ual to zero.** t
1e260 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73  urns off all bus
1e270 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a  y handlers..**.*
1e280 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e  * ^(There can on
1e290 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
1e2a0 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
1e2b0 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
1e2c0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1e2d0 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69 76  tion] at any giv
1e2e0 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61  en moment.  If a
1e2f0 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64  nother busy hand
1e300 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e  ler.** was defin
1e310 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69  ed  (using [sqli
1e320 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1e330 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61  ()]) prior to ca
1e340 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f  lling.** this ro
1e350 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65  utine, that othe
1e360 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  r busy handler i
1e370 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a  s cleared.)^.**.
1e380 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50  ** See also:  [P
1e390 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f  RAGMA busy_timeo
1e3a0 75 74 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ut].*/.SQLITE_AP
1e3b0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
1e3c0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 75 73  CALL sqlite3_bus
1e3d0 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65  y_timeout(sqlite
1e3e0 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a  3*, int ms);../*
1e3f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
1e400 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e  nvenience Routin
1e410 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51  es For Running Q
1e420 75 65 72 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44  ueries.** METHOD
1e430 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
1e440 54 68 69 73 20 69 73 20 61 20 6c 65 67 61 63 79  This is a legacy
1e450 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
1e460 69 73 20 70 72 65 73 65 72 76 65 64 20 66 6f 72  is preserved for
1e470 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
1e480 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65  tibility..** Use
1e490 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61   of this interfa
1e4a0 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d  ce is not recomm
1e4b0 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66  ended..**.** Def
1e4c0 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65  inition: A <b>re
1e4d0 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69  sult table</b> i
1e4e0 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74  s memory data st
1e4f0 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20  ructure created 
1e500 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  by the.** [sqlit
1e510 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
1e520 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65  interface.  A re
1e530 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72  sult table recor
1e540 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65  ds the.** comple
1e550 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  te query results
1e560 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72   from one or mor
1e570 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a  e queries..**.**
1e580 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65   The table conce
1e590 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75  ptually has a nu
1e5a0 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64  mber of rows and
1e5b0 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a   columns.  But.*
1e5c0 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20  * these numbers 
1e5d0 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20  are not part of 
1e5e0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
1e5f0 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a   itself.  These.
1e600 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f  ** numbers are o
1e610 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65  btained separate
1e620 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68  ly.  Let N be th
1e630 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
1e640 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65  .** and M be the
1e650 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
1e660 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  ns..**.** A resu
1e670 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61  lt table is an a
1e680 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
1e690 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
1e6a0 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
1e6b0 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  s..** There are 
1e6c0 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73  (N+1)*M elements
1e6d0 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20   in the array.  
1e6e0 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e  The first M poin
1e6f0 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f  ters point.** to
1e700 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1e710 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63   strings that  c
1e720 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73  ontain the names
1e730 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e   of the columns.
1e740 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e  .** The remainin
1e750 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f  g entries all po
1e760 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73  int to query res
1e770 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75  ults.  NULL valu
1e780 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20  es result.** in 
1e790 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20  NULL pointers.  
1e7a0 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73  All other values
1e7b0 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54   are in their UT
1e7c0 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  F-8 zero-termina
1e7d0 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65  ted.** string re
1e7e0 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20  presentation as 
1e7f0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
1e800 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
1e810 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  ()]..**.** A res
1e820 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20  ult table might 
1e830 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f  consist of one o
1e840 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c  r more memory al
1e850 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74  locations..** It
1e860 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
1e870 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61  pass a result ta
1e880 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20  ble directly to 
1e890 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1e8a0 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  ..** A result ta
1e8b0 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65  ble should be de
1e8c0 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20  allocated using 
1e8d0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
1e8e0 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ble()]..**.** ^(
1e8f0 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66  As an example of
1e900 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1e910 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73  e format, suppos
1e920 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74  e a query result
1e930 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  .** is as follow
1e940 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1e950 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
1e960 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20       Name       
1e970 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20   | Age.**       
1e980 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d   ---------------
1e990 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20  --------.**     
1e9a0 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c     Alice       |
1e9b0 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f   43.**        Bo
1e9c0 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a  b         | 28.*
1e9d0 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20  *        Cindy  
1e9e0 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70       | 21.** </p
1e9f0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1ea00 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  .**.** There are
1ea10 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d   two column (M==
1ea20 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77  2) and three row
1ea30 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20  s (N==3).  Thus 
1ea40 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61  the.** result ta
1ea50 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65  ble has 8 entrie
1ea60 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20  s.  Suppose the 
1ea70 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
1ea80 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20  stored.** in an 
1ea90 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65  array names azRe
1eaa0 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65  sult.  Then azRe
1eab0 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20  sult holds this 
1eac0 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c  content:.**.** <
1ead0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1eae0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1eaf0 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61  ult&#91;0] = "Na
1eb00 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  me";.**        a
1eb10 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d  zResult&#91;1] =
1eb20 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20   "Age";.**      
1eb30 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32    azResult&#91;2
1eb40 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20  ] = "Alice";.** 
1eb50 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1eb60 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a  #91;3] = "43";.*
1eb70 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1eb80 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22  t&#91;4] = "Bob"
1eb90 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1eba0 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32  sult&#91;5] = "2
1ebb0 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  8";.**        az
1ebc0 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20  Result&#91;6] = 
1ebd0 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20  "Cindy";.**     
1ebe0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1ebf0 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f  7] = "21";.** </
1ec00 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1ec10 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  >)^.**.** ^The s
1ec20 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1ec30 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c  () function eval
1ec40 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72  uates one or mor
1ec50 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73  e.** semicolon-s
1ec60 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61  eparated SQL sta
1ec70 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a  tements in the z
1ec80 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
1ec90 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  TF-8.** string o
1eca0 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65  f its 2nd parame
1ecb0 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ter and returns 
1ecc0 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74  a result table t
1ecd0 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72  o the.** pointer
1ece0 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72   given in its 3r
1ecf0 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
1ed00 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70  ** After the app
1ed10 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e  lication has fin
1ed20 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72  ished with the r
1ed30 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74  esult from sqlit
1ed40 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a  e3_get_table(),.
1ed50 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73 20  ** it must pass 
1ed60 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
1ed70 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69   pointer to sqli
1ed80 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
1ed90 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20   in order to.** 
1eda0 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
1edb0 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c  ry that was mall
1edc0 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f  oced.  Because o
1edd0 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a  f the way the.**
1ede0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1edf0 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68  ()] happens with
1ee00 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  in sqlite3_get_t
1ee10 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c  able(), the call
1ee20 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ing.** function 
1ee30 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20  must not try to 
1ee40 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72  call [sqlite3_fr
1ee50 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20  ee()] directly. 
1ee60 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65   Only.** [sqlite
1ee70 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20  3_free_table()] 
1ee80 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61  is able to relea
1ee90 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  se the memory pr
1eea0 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c  operly and safel
1eeb0 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  y..**.** The sql
1eec0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1eed0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d   interface is im
1eee0 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77  plemented as a w
1eef0 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a  rapper around.**
1ef00 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
1ef10 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  ].  The sqlite3_
1ef20 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74  get_table() rout
1ef30 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  ine does not hav
1ef40 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61  e access.** to a
1ef50 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  ny internal data
1ef60 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53   structures of S
1ef70 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20  QLite.  It uses 
1ef80 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a  only the public.
1ef90 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66  ** interface def
1efa0 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61  ined here.  As a
1efb0 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72   consequence, er
1efc0 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20  rors that occur 
1efd0 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65  in the.** wrappe
1efe0 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20  r layer outside 
1eff0 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  of the internal 
1f000 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
1f010 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a   call are not.**
1f020 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75   reflected in su
1f030 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
1f040 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
1f050 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  de()] or.** [sql
1f060 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
1f070 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
1f080 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
1f090 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1f0a0 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  le(.  sqlite3 *d
1f0b0 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41  b,          /* A
1f0c0 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  n open database 
1f0d0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1f0e0 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51  *zSql,     /* SQ
1f0f0 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65  L to be evaluate
1f100 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70  d */.  char ***p
1f110 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20  azResult,    /* 
1f120 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71  Results of the q
1f130 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  uery */.  int *p
1f140 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20  nRow,           
1f150 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
1f160 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e  ult rows written
1f170 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a   here */.  int *
1f180 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20  pnColumn,       
1f190 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
1f1a0 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69  sult columns wri
1f1b0 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63  tten here */.  c
1f1c0 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20  har **pzErrmsg  
1f1d0 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73       /* Error ms
1f1e0 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  g written here *
1f1f0 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  /.);.SQLITE_API 
1f200 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43  void SQLITE_STDC
1f210 41 4c 4c 20 73 71 6c 69 74 65 33 5f 66 72 65 65  ALL sqlite3_free
1f220 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65  _table(char **re
1f230 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  sult);../*.** CA
1f240 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65  PI3REF: Formatte
1f250 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e  d String Printin
1f260 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
1f270 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1f280 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73   are work-alikes
1f290 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28   of the "printf(
1f2a0 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e  )" family of fun
1f2b0 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74  ctions.** from t
1f2c0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
1f2d0 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20  brary..** These 
1f2e0 72 6f 75 74 69 6e 65 73 20 75 6e 64 65 72 73 74  routines underst
1f2f0 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74 68 65 20  and most of the 
1f300 63 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d 61  common K&R forma
1f310 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a  tting options,.*
1f320 2a 20 70 6c 75 73 20 73 6f 6d 65 20 61 64 64 69  * plus some addi
1f330 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64  tional non-stand
1f340 61 72 64 20 66 6f 72 6d 61 74 73 2c 20 64 65 74  ard formats, det
1f350 61 69 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20  ailed below..** 
1f360 4e 6f 74 65 20 74 68 61 74 20 73 6f 6d 65 20 6f  Note that some o
1f370 66 20 74 68 65 20 6d 6f 72 65 20 6f 62 73 63 75  f the more obscu
1f380 72 65 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  re formatting op
1f390 74 69 6f 6e 73 20 66 72 6f 6d 20 72 65 63 65 6e  tions from recen
1f3a0 74 0a 2a 2a 20 43 2d 6c 69 62 72 61 72 79 20 73  t.** C-library s
1f3b0 74 61 6e 64 61 72 64 73 20 61 72 65 20 6f 6d 69  tandards are omi
1f3c0 74 74 65 64 20 66 72 6f 6d 20 74 68 69 73 20 69  tted from this i
1f3d0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a  mplementation..*
1f3e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1f3f0 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20  3_mprintf() and 
1f400 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
1f410 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74  () routines writ
1f420 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c  e their.** resul
1f430 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  ts into memory o
1f440 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
1f450 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
1f460 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20  .** The strings 
1f470 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73  returned by thes
1f480 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73  e two routines s
1f490 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65  hould be.** rele
1f4a0 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ased by [sqlite3
1f4b0 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68  _free()].  ^Both
1f4c0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1f4d0 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
1f4e0 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d  er if [sqlite3_m
1f4f0 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62  alloc()] is unab
1f500 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65  le to allocate e
1f510 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20  nough.** memory 
1f520 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75  to hold the resu
1f530 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a  lting string..**
1f540 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
1f550 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  3_snprintf() rou
1f560 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
1f570 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20  to "snprintf()" 
1f580 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e  from.** the stan
1f590 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20  dard C library. 
1f5a0 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77   The result is w
1f5b0 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a  ritten into the.
1f5c0 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69  ** buffer suppli
1f5d0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
1f5e0 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65   parameter whose
1f5f0 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62   size is given b
1f600 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70  y.** the first p
1f610 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74  arameter. Note t
1f620 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66  hat the order of
1f630 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77   the.** first tw
1f640 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  o parameters is 
1f650 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e  reversed from sn
1f660 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69  printf().)^  Thi
1f670 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f  s is an.** histo
1f680 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74  rical accident t
1f690 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69  hat cannot be fi
1f6a0 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  xed without brea
1f6b0 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64  king.** backward
1f6c0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
1f6d0 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68    ^(Note also th
1f6e0 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  at sqlite3_snpri
1f6f0 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ntf().** returns
1f700 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
1f710 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64  s buffer instead
1f720 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
1f730 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  f.** characters 
1f740 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e  actually written
1f750 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72   into the buffer
1f760 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68  .)^  We admit th
1f770 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  at.** the number
1f780 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77   of characters w
1f790 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20  ritten would be 
1f7a0 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65  a more useful re
1f7b0 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75  turn.** value bu
1f7c0 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e  t we cannot chan
1f7d0 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ge the implement
1f7e0 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
1f7f0 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e  _snprintf().** n
1f800 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ow without break
1f810 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  ing compatibilit
1f820 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e  y..**.** ^As lon
1f830 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20  g as the buffer 
1f840 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20  size is greater 
1f850 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74  than zero, sqlit
1f860 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1f870 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
1f880 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61   the buffer is a
1f890 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
1f8a0 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72  nated.  ^The fir
1f8b0 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  st.** parameter 
1f8c0 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c  "n" is the total
1f8d0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
1f8e0 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73  fer, including s
1f8f0 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  pace for.** the 
1f900 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
1f910 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74    So the longest
1f920 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e   string that can
1f930 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a   be completely.*
1f940 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62  * written will b
1f950 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73  e n-1 characters
1f960 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1f970 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29  ite3_vsnprintf()
1f980 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61   routine is a va
1f990 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66  rargs version of
1f9a0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1f9b0 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  f()..**.** These
1f9c0 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d   routines all im
1f9d0 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64  plement some add
1f9e0 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69  itional formatti
1f9f0 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68  ng.** options th
1fa00 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f  at are useful fo
1fa10 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53  r constructing S
1fa20 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
1fa30 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75  * All of the usu
1fa40 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d  al printf() form
1fa50 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61  atting options a
1fa60 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69  pply.  In additi
1fa70 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20  on, there.** is 
1fa80 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20  are "%q", "%Q", 
1fa90 22 25 77 22 20 61 6e 64 20 22 25 7a 22 20 6f 70  "%w" and "%z" op
1faa0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  tions..**.** ^(T
1fab0 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72  he %q option wor
1fac0 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68  ks like %s in th
1fad0 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65  at it substitute
1fae0 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  s a nul-terminat
1faf0 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f  ed.** string fro
1fb00 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c  m the argument l
1fb10 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73  ist.  But %q als
1fb20 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20  o doubles every 
1fb30 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a  '\'' character..
1fb40 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65  ** %q is designe
1fb50 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65  d for use inside
1fb60 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
1fb70 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e  l.)^  By doublin
1fb80 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63  g each '\''.** c
1fb90 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61  haracter it esca
1fba0 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74  pes that charact
1fbb0 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74  er and allows it
1fbc0 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20   to be inserted 
1fbd0 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69  into.** the stri
1fbe0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78  ng..**.** For ex
1fbf0 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68  ample, assume th
1fc00 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c  e string variabl
1fc10 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73  e zText contains
1fc20 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73   text as follows
1fc30 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1fc40 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1fc50 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27  ar *zText = "It'
1fc60 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b  s a happy day!";
1fc70 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1fc80 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e  kquote>.**.** On
1fc90 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74  e can use this t
1fca0 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  ext in an SQL st
1fcb0 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f  atement as follo
1fcc0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1fcd0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1fce0 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
1fcf0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
1fd00 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
1fd10 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a  VALUES('%q')", z
1fd20 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
1fd30 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
1fd40 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
1fd50 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
1fd60 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
1fd70 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1fd80 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20   Because the %q 
1fd90 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73  format string is
1fda0 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20   used, the '\'' 
1fdb0 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65  character in zTe
1fdc0 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64  xt.** is escaped
1fdd0 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e   and the SQL gen
1fde0 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c  erated is as fol
1fdf0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1fe00 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1fe10 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
1fe20 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
1fe30 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
1fe40 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ).** </pre></blo
1fe50 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1fe60 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20  his is correct. 
1fe70 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20   Had we used %s 
1fe80 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74  instead of %q, t
1fe90 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c  he generated SQL
1fea0 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c  .** would have l
1feb0 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a  ooked like this:
1fec0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1fed0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
1fee0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
1fef0 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68  VALUES('It's a h
1ff00 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20  appy day!');.** 
1ff10 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1ff20 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  te>.**.** This s
1ff30 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73  econd example is
1ff40 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65   an SQL syntax e
1ff50 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65  rror.  As a gene
1ff60 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f  ral rule you sho
1ff70 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73  uld.** always us
1ff80 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20  e %q instead of 
1ff90 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  %s when insertin
1ffa0 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74  g text into a st
1ffb0 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a  ring literal..**
1ffc0 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74  .** ^(The %Q opt
1ffd0 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
1ffe0 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f  q except it also
1fff0 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f   adds single quo
20000 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68  tes around.** th
20010 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  e outside of the
20020 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20   total string.  
20030 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66  Additionally, if
20040 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
20050 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e  n the.** argumen
20060 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c  t list is a NULL
20070 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62   pointer, %Q sub
20080 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78  stitutes the tex
20090 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75  t "NULL" (withou
200a0 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74  t.** single quot
200b0 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20  es).)^  So, for 
200c0 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75  example, one cou
200d0 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ld say:.**.** <b
200e0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
200f0 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
20100 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
20110 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
20120 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c  ble VALUES(%Q)",
20130 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
20140 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
20150 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
20160 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
20170 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
20180 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
20190 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76  ** The code abov
201a0 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20  e will render a 
201b0 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74  correct SQL stat
201c0 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51  ement in the zSQ
201d0 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76  L.** variable ev
201e0 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20  en if the zText 
201f0 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55  variable is a NU
20200 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
20210 2a 20 5e 28 54 68 65 20 22 25 77 22 20 66 6f 72  * ^(The "%w" for
20220 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69  matting option i
20230 73 20 6c 69 6b 65 20 22 25 71 22 20 65 78 63 65  s like "%q" exce
20240 70 74 20 74 68 61 74 20 69 74 20 65 78 70 65 63  pt that it expec
20250 74 73 20 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74  ts to.** be cont
20260 61 69 6e 65 64 20 77 69 74 68 69 6e 20 64 6f 75  ained within dou
20270 62 6c 65 2d 71 75 6f 74 65 73 20 69 6e 73 74 65  ble-quotes inste
20280 61 64 20 6f 66 20 73 69 6e 67 6c 65 20 71 75 6f  ad of single quo
20290 74 65 73 2c 20 61 6e 64 20 69 74 0a 2a 2a 20 65  tes, and it.** e
202a0 73 63 61 70 65 73 20 74 68 65 20 64 6f 75 62 6c  scapes the doubl
202b0 65 2d 71 75 6f 74 65 20 63 68 61 72 61 63 74 65  e-quote characte
202c0 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  r instead of the
202d0 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a   single-quote.**
202e0 20 63 68 61 72 61 63 74 65 72 2e 29 5e 20 20 54   character.)^  T
202f0 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69  he "%w" formatti
20300 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 74  ng option is int
20310 65 6e 64 65 64 20 66 6f 72 20 73 61 66 65 6c 79  ended for safely
20320 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 61   inserting.** ta
20330 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e  ble and column n
20340 61 6d 65 73 20 69 6e 74 6f 20 61 20 63 6f 6e 73  ames into a cons
20350 74 72 75 63 74 65 64 20 53 51 4c 20 73 74 61 74  tructed SQL stat
20360 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ement..**.** ^(T
20370 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69  he "%z" formatti
20380 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  ng option works 
20390 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69  like "%s" but wi
203a0 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69  th the.** additi
203b0 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68  on that after th
203c0 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65  e string has bee
203d0 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65  n read and copie
203e0 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65  d into.** the re
203f0 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66  sult, [sqlite3_f
20400 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ree()] is called
20410 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   on the input st
20420 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54  ring.)^.*/.SQLIT
20430 45 5f 41 50 49 20 63 68 61 72 20 2a 53 51 4c 49  E_API char *SQLI
20440 54 45 5f 43 44 45 43 4c 20 73 71 6c 69 74 65 33  TE_CDECL sqlite3
20450 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  _mprintf(const c
20460 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54  har*,...);.SQLIT
20470 45 5f 41 50 49 20 63 68 61 72 20 2a 53 51 4c 49  E_API char *SQLI
20480 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
20490 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73  e3_vmprintf(cons
204a0 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
204b0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68  );.SQLITE_API ch
204c0 61 72 20 2a 53 51 4c 49 54 45 5f 43 44 45 43 4c  ar *SQLITE_CDECL
204d0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
204e0 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73  f(int,char*,cons
204f0 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53  t char*, ...);.S
20500 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a  QLITE_API char *
20510 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
20520 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66  qlite3_vsnprintf
20530 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74  (int,char*,const
20540 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
20550 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
20560 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
20570 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a  tion Subsystem.*
20580 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  *.** The SQLite 
20590 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20  core uses these 
205a0 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66  three routines f
205b0 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77  or all of its ow
205c0 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65  n.** internal me
205d0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
205e0 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e  needs. "Core" in
205f0 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65   the previous se
20600 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e  ntence.** does n
20610 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61  ot include opera
20620 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
20630 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65  ific VFS impleme
20640 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a  ntation.  The.**
20650 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65   Windows VFS use
20660 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28  s native malloc(
20670 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72  ) and free() for
20680 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73   some operations
20690 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
206a0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f  ite3_malloc() ro
206b0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
206c0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f  pointer to a blo
206d0 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20  ck.** of memory 
206e0 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
206f0 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72   in length, wher
20700 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d  e N is the param
20710 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  eter..** ^If sql
20720 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
20730 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69   unable to obtai
20740 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65  n sufficient fre
20750 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20  e.** memory, it 
20760 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
20770 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65  ointer.  ^If the
20780 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a   parameter N to.
20790 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
207a0 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e  c() is zero or n
207b0 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c  egative then sql
207c0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65  ite3_malloc() re
207d0 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  turns.** a NULL 
207e0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
207f0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  The sqlite3_mall
20800 6f 63 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20  oc64(N) routine 
20810 77 6f 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a  works just like.
20820 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
20830 63 28 4e 29 20 65 78 63 65 70 74 20 74 68 61 74  c(N) except that
20840 20 4e 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65   N is an unsigne
20850 64 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  d 64-bit integer
20860 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61   instead.** of a
20870 20 73 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69   signed 32-bit i
20880 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43  nteger..**.** ^C
20890 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  alling sqlite3_f
208a0 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69  ree() with a poi
208b0 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20  nter previously 
208c0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
208d0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
208e0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
208f0 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68  oc() releases th
20900 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20  at memory so.** 
20910 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65  that it might be
20920 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73   reused.  ^The s
20930 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f  qlite3_free() ro
20940 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f  utine is.** a no
20950 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64  -op if is called
20960 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
20970 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61  nter.  Passing a
20980 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
20990 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
209a0 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20  () is harmless. 
209b0 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65   After being fre
209c0 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68  ed, memory.** sh
209d0 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20  ould neither be 
209e0 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e  read nor written
209f0 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20  .  Even reading 
20a00 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64  previously freed
20a10 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74  .** memory might
20a20 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67   result in a seg
20a30 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20  mentation fault 
20a40 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
20a50 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79  error..** Memory
20a60 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73   corruption, a s
20a70 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
20a80 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65  t, or other seve
20a90 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68  re error.** migh
20aa0 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69  t result if sqli
20ab0 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61  te3_free() is ca
20ac0 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d  lled with a non-
20ad0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61  NULL pointer tha
20ae0 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74  t.** was not obt
20af0 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74  ained from sqlit
20b00 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
20b10 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
20b20 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
20b30 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
20b40 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
20b50 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61  mpts to resize a
20b60 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79  .** prior memory
20b70 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f   allocation X to
20b80 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62   be at least N b
20b90 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
20ba0 20 58 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   X parameter to 
20bb0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
20bc0 58 2c 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c  X,N).** is a NUL
20bd0 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69  L pointer then i
20be0 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69  ts behavior is i
20bf0 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c  dentical to call
20c00 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  ing.** sqlite3_m
20c10 61 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66  alloc(N)..** ^If
20c20 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72   the N parameter
20c30 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
20c40 6c 6f 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f  loc(X,N) is zero
20c50 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20   or.** negative 
20c60 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
20c70 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65  r is exactly the
20c80 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67   same as calling
20c90 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65  .** sqlite3_free
20ca0 28 58 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33  (X)..** ^sqlite3
20cb0 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65  _realloc(X,N) re
20cc0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
20cd0 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  to a memory allo
20ce0 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20  cation.** of at 
20cf0 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
20d00 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66   size or NULL if
20d10 20 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65   insufficient me
20d20 6d 6f 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c  mory is availabl
20d30 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74  e..** ^If M is t
20d40 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70  he size of the p
20d50 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c  rior allocation,
20d60 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62   then min(N,M) b
20d70 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70  ytes.** of the p
20d80 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
20d90 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20  are copied into 
20da0 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
20db0 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64   buffer returned
20dc0 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72  .** by sqlite3_r
20dd0 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20  ealloc(X,N) and 
20de0 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
20df0 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a  tion is freed..*
20e00 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65  * ^If sqlite3_re
20e10 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72  alloc(X,N) retur
20e20 6e 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73  ns NULL and N is
20e30 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20   positive, then 
20e40 74 68 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c  the.** prior all
20e50 6f 63 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66  ocation is not f
20e60 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  reed..**.** ^The
20e70 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
20e80 36 34 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63  64(X,N) interfac
20e90 65 73 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d  es works the sam
20ea0 65 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  e as.** sqlite3_
20eb0 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63  realloc(X,N) exc
20ec0 65 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 20  ept that N is a 
20ed0 36 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20  64-bit unsigned 
20ee0 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a  integer instead.
20ef0 2a 2a 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73  ** of a 32-bit s
20f00 69 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a  igned integer..*
20f10 2a 0a 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20  *.** ^If X is a 
20f20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
20f30 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74  n previously obt
20f40 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74  ained from sqlit
20f50 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20  e3_malloc(),.** 
20f60 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34  sqlite3_malloc64
20f70 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  (), sqlite3_real
20f80 6c 6f 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65  loc(), or sqlite
20f90 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74  3_realloc64(), t
20fa0 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  hen.** sqlite3_m
20fb0 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20  size(X) returns 
20fc0 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74  the size of that
20fd0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
20fe0 6f 6e 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20  on in bytes..** 
20ff0 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72  ^The value retur
21000 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  ned by sqlite3_m
21010 73 69 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65  size(X) might be
21020 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65   larger than the
21030 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79   number.** of by
21040 74 65 73 20 72 65 71 75 65 73 74 65 64 20 77 68  tes requested wh
21050 65 6e 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74  en X was allocat
21060 65 64 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20  ed.  ^If X is a 
21070 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
21080 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69  n.** sqlite3_msi
21090 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65  ze(X) returns ze
210a0 72 6f 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73  ro.  If X points
210b0 20 74 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68   to something th
210c0 61 74 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65  at is not.** the
210d0 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65   beginning of me
210e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c  mory allocation,
210f0 20 6f 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73   or if it points
21100 20 74 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a   to a formerly.*
21110 2a 20 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61  * valid memory a
21120 6c 6c 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68  llocation that h
21130 61 73 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65  as now been free
21140 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  d, then the beha
21150 76 69 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  vior.** of sqlit
21160 65 33 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75  e3_msize(X) is u
21170 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73  ndefined and pos
21180 73 69 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a  sibly harmful..*
21190 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79  *.** ^The memory
211a0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
211b0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73  ite3_malloc(), s
211c0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
211d0 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  ,.** sqlite3_mal
211e0 6c 6f 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c  loc64(), and sql
211f0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29  ite3_realloc64()
21200 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c  .** is always al
21210 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73  igned to at leas
21220 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e  t an 8 byte boun
21230 64 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a  dary, or to a.**
21240 20 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   4 byte boundary
21250 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
21260 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d  4_BYTE_ALIGNED_M
21270 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74  ALLOC] compile-t
21280 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73  ime.** option is
21290 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20   used..**.** In 
212a0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
212b0 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20  .5.0 and 3.5.1, 
212c0 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20  it was possible 
212d0 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65  to define.** the
212e0 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d   SQLITE_OMIT_MEM
212f0 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77  ORY_ALLOCATION w
21300 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65  hich would cause
21310 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a   the built-in.**
21320 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
21330 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
21340 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e  s to be omitted.
21350 20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74    That capabilit
21360 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  y.** is no longe
21370 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c  r provided.  Onl
21380 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  y built-in memor
21390 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e  y allocators can
213a0 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   be used..**.** 
213b0 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20  Prior to SQLite 
213c0 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20  version 3.7.10, 
213d0 74 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69  the Windows OS i
213e0 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63  nterface layer c
213f0 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73  alled.** the sys
21400 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  tem malloc() and
21410 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79   free() directly
21420 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67   when converting
21430 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65  .** filenames be
21440 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20  tween the UTF-8 
21450 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79  encoding used by
21460 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77   SQLite.** and w
21470 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65  hatever filename
21480 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65   encoding is use
21490 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75  d by the particu
214a0 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69  lar Windows.** i
214b0 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65  nstallation.  Me
214c0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
214d0 65 72 72 6f 72 73 20 77 65 72 65 20 64 65 74 65  errors were dete
214e0 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65  cted, but.** the
214f0 79 20 77 65 72 65 20 72 65 70 6f 72 74 65 64 20  y were reported 
21500 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f  back as [SQLITE_
21510 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20  CANTOPEN] or.** 
21520 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72  [SQLITE_IOERR] r
21530 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  ather than [SQLI
21540 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a  TE_NOMEM]..**.**
21550 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67   The pointer arg
21560 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74  uments to [sqlit
21570 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b  e3_free()] and [
21580 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
21590 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69  )].** must be ei
215a0 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73  ther NULL or els
215b0 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69  e pointers obtai
215c0 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72  ned from a prior
215d0 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  .** invocation o
215e0 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
215f0 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
21600 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74  _realloc()] that
21610 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74   have.** not yet
21620 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a   been released..
21630 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  **.** The applic
21640 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72  ation must not r
21650 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79  ead or write any
21660 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c   part of.** a bl
21670 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66  ock of memory af
21680 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
21690 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a  released using.*
216a0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
216b0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
216c0 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51  ealloc()]..*/.SQ
216d0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53  LITE_API void *S
216e0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
216f0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74  lite3_malloc(int
21700 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
21710 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  id *SQLITE_STDCA
21720 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  LL sqlite3_mallo
21730 63 36 34 28 73 71 6c 69 74 65 33 5f 75 69 6e 74  c64(sqlite3_uint
21740 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  64);.SQLITE_API 
21750 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44  void *SQLITE_STD
21760 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 61  CALL sqlite3_rea
21770 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29  lloc(void*, int)
21780 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
21790 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  d *SQLITE_STDCAL
217a0 4c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  L sqlite3_reallo
217b0 63 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74  c64(void*, sqlit
217c0 65 33 5f 75 69 6e 74 36 34 29 3b 0a 53 51 4c 49  e3_uint64);.SQLI
217d0 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49  TE_API void SQLI
217e0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
217f0 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a  e3_free(void*);.
21800 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
21810 65 33 5f 75 69 6e 74 36 34 20 53 51 4c 49 54 45  e3_uint64 SQLITE
21820 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
21830 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a  _msize(void*);..
21840 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
21850 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72  Memory Allocator
21860 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a   Statistics.**.*
21870 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65  * SQLite provide
21880 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65  s these two inte
21890 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72  rfaces for repor
218a0 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74  ting on the stat
218b0 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  us.** of the [sq
218c0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
218d0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
218e0 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
218f0 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f  realloc()].** ro
21900 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f  utines, which fo
21910 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20  rm the built-in 
21920 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
21930 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a  n subsystem..**.
21940 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
21950 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
21960 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
21970 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
21980 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  tes.** of memory
21990 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74   currently outst
219a0 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64  anding (malloced
219b0 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e   but not freed).
219c0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
219d0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
219e0 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  er()] routine re
219f0 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75  turns the maximu
21a00 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73  m.** value of [s
21a10 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
21a20 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20  ed()] since the 
21a30 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
21a40 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65  ** was last rese
21a50 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  t.  ^The values 
21a60 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
21a70 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
21a80 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
21a90 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
21aa0 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20  ater()] include 
21ab0 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20  any overhead.** 
21ac0 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20  added by SQLite 
21ad0 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74  in its implement
21ae0 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
21af0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20  3_malloc()],.** 
21b00 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64  but not overhead
21b10 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e   added by the an
21b20 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73  y underlying sys
21b30 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72  tem library.** r
21b40 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71  outines that [sq
21b50 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
21b60 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  may call..**.** 
21b70 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68  ^The memory high
21b80 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72  -water mark is r
21b90 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72  eset to the curr
21ba0 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  ent value of.** 
21bb0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
21bc0 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f  used()] if and o
21bd0 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d  nly if the param
21be0 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
21bf0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
21c00 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e  ater()] is true.
21c10 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74    ^The value ret
21c20 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  urned.** by [sql
21c30 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
21c40 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65  water(1)] is the
21c50 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
21c60 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65  .** prior to the
21c70 20 72 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54   reset..*/.SQLIT
21c80 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e  E_API sqlite3_in
21c90 74 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41  t64 SQLITE_STDCA
21ca0 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  LL sqlite3_memor
21cb0 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 53 51  y_used(void);.SQ
21cc0 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
21cd0 5f 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 54  _int64 SQLITE_ST
21ce0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 65  DCALL sqlite3_me
21cf0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69  mory_highwater(i
21d00 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a  nt resetFlag);..
21d10 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
21d20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75  Pseudo-Random Nu
21d30 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a  mber Generator.*
21d40 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74  *.** SQLite cont
21d50 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c  ains a high-qual
21d60 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  ity pseudo-rando
21d70 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74  m number generat
21d80 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74  or (PRNG) used t
21d90 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64  o.** select rand
21da0 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49  om [ROWID | ROWI
21db0 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69  Ds] when inserti
21dc0 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69  ng new records i
21dd0 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74  nto a table that
21de0 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73  .** already uses
21df0 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73   the largest pos
21e00 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20  sible [ROWID].  
21e10 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f  The PRNG is also
21e20 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65   used for.** the
21e30 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d   build-in random
21e40 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f  () and randomblo
21e50 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  b() SQL function
21e60 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61  s.  This interfa
21e70 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70  ce allows.** app
21e80 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63  lications to acc
21e90 65 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e  ess the same PRN
21ea0 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70  G for other purp
21eb0 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63  oses..**.** ^A c
21ec0 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74  all to this rout
21ed0 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74  ine stores N byt
21ee0 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
21ef0 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a   into buffer P..
21f00 2a 2a 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65  ** ^The P parame
21f10 74 65 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c  ter can be a NUL
21f20 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
21f30 20 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e   ^If this routin
21f40 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70  e has not been p
21f50 72 65 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64  reviously called
21f60 20 6f 72 20 69 66 20 74 68 65 20 70 72 65 76 69   or if the previ
21f70 6f 75 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20  ous.** call had 
21f80 4e 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20  N less than one 
21f90 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  or a NULL pointe
21fa0 72 20 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68  r for P, then th
21fb0 65 20 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65  e PRNG is.** see
21fc0 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d  ded using random
21fd0 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72  ness obtained fr
21fe0 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65  om the xRandomne
21ff0 73 73 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20  ss method of.** 
22000 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
22010 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
22020 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65  ..** ^If the pre
22030 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68  vious call to th
22040 69 73 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61  is routine had a
22050 6e 20 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65  n N of 1 or more
22060 20 61 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55   and a.** non-NU
22070 4c 4c 20 50 20 74 68 65 6e 20 74 68 65 20 70 73  LL P then the ps
22080 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20  eudo-randomness 
22090 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20  is generated.** 
220a0 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77  internally and w
220b0 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20  ithout recourse 
220c0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
220d0 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73  vfs] xRandomness
220e0 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53  .** method..*/.S
220f0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53  QLITE_API void S
22100 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
22110 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73  lite3_randomness
22120 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29  (int N, void *P)
22130 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
22140 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20  F: Compile-Time 
22150 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61  Authorization Ca
22160 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f  llbacks.** METHO
22170 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
22180 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
22190 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68  egisters an auth
221a0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
221b0 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
221c0 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
221d0 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70  onnection], supp
221e0 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  lied in the firs
221f0 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  t argument..** ^
22200 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
22210 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
22220 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
22230 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63  ents are being c
22240 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73  ompiled.** by [s
22250 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
22260 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
22270 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
22280 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v2()],.** [sq
22290 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
222a0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
222b0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
222c0 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a    ^At various.**
222d0 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74   points during t
222e0 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70  he compilation p
222f0 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63  rocess, as logic
22300 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65   is being create
22310 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20  d.** to perform 
22320 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c  various actions,
22330 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
22340 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
22350 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66  ked to.** see if
22360 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61   those actions a
22370 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68  re allowed.  ^Th
22380 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
22390 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20  lback should.** 
223a0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
223b0 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20  K] to allow the 
223c0 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f  action, [SQLITE_
223d0 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c  IGNORE] to disal
223e0 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69  low the.** speci
223f0 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61  fic action but a
22400 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61  llow the SQL sta
22410 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e  tement to contin
22420 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ue to be.** comp
22430 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45  iled, or [SQLITE
22440 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20  _DENY] to cause 
22450 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73  the entire SQL s
22460 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a  tatement to be.*
22470 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20  * rejected with 
22480 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74  an error.  ^If t
22490 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
224a0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
224b0 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65  * any value othe
224c0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49  r than [SQLITE_I
224d0 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  GNORE], [SQLITE_
224e0 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OK], or [SQLITE_
224f0 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  DENY].** then th
22500 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
22510 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
22520 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
22530 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68   triggered.** th
22540 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  e authorizer wil
22550 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
22560 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
22570 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c  .** When the cal
22580 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
22590 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20  QLITE_OK], that 
225a0 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74  means the operat
225b0 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  ion.** requested
225c0 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74   is ok.  ^When t
225d0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
225e0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59  rns [SQLITE_DENY
225f0 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ], the.** [sqlit
22600 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
22610 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
22620 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
22630 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  ed the.** author
22640 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
22650 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
22660 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20  sage explaining 
22670 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69  that.** access i
22680 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a  s denied. .**.**
22690 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
226a0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
226b0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
226c0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
226d0 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
226e0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
226f0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
22700 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20  er() interface. 
22710 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
22720 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
22730 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
22740 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43  nteger [SQLITE_C
22750 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64  OPY | action cod
22760 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65  e] that specifie
22770 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75  s.** the particu
22780 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  lar action to be
22790 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68   authorized. ^Th
227a0 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20  e third through 
227b0 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73  sixth parameters
227c0 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
227d0 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72  ack are zero-ter
227e0 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
227f0 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64  that contain add
22800 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69  itional.** detai
22810 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74  ls about the act
22820 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
22830 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ized..**.** ^If 
22840 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  the action code 
22850 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d  is [SQLITE_READ]
22860 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  .** and the call
22870 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
22880 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
22890 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
228a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74  ed statement] st
228b0 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74  atement is const
228c0 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69  ructed to substi
228d0 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76  tute.** a NULL v
228e0 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66  alue in place of
228f0 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
22900 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  n that would hav
22910 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69  e.** been read i
22920 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61  f [SQLITE_OK] ha
22930 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e  d been returned.
22940 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47    The [SQLITE_IG
22950 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20  NORE].** return 
22960 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64  can be used to d
22970 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64  eny an untrusted
22980 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20   user access to 
22990 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f  individual.** co
229a0 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65  lumns of a table
229b0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  ..** ^If the act
229c0 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
229d0 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20  ITE_DELETE] and 
229e0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
229f0 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
22a00 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
22a10 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74   [DELETE] operat
22a20 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74  ion proceeds but
22a30 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74   the.** [truncat
22a40 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20  e optimization] 
22a50 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20  is disabled and 
22a60 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c  all rows are del
22a70 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c  eted individuall
22a80 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68  y..**.** An auth
22a90 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77  orizer is used w
22aa0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
22ab0 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67  pare | preparing
22ac0 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  ].** SQL stateme
22ad0 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72  nts from an untr
22ae0 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f  usted source, to
22af0 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
22b00 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
22b10 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f  ** do not try to
22b20 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65   access data the
22b30 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65  y are not allowe
22b40 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61  d to see, or tha
22b50 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
22b60 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20   try to execute 
22b70 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d  malicious statem
22b80 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65  ents that damage
22b90 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20   the database.  
22ba0 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
22bb0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  an application m
22bc0 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20  ay allow a user 
22bd0 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61  to enter arbitra
22be0 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65  ry.** SQL querie
22bf0 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e  s for evaluation
22c00 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20   by a database. 
22c10 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61   But the applica
22c20 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  tion does.** not
22c30 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74   want the user t
22c40 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b  o be able to mak
22c50 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e  e arbitrary chan
22c60 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61  ges to the.** da
22c70 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68  tabase.  An auth
22c80 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65  orizer could the
22c90 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63  n be put in plac
22ca0 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75  e while the.** u
22cb0 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20  ser-entered SQL 
22cc0 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65  is being [sqlite
22cd0 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
22ce0 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69  ared] that.** di
22cf0 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69  sallows everythi
22d00 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43  ng except [SELEC
22d10 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  T] statements..*
22d20 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
22d30 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70  s that need to p
22d40 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20  rocess SQL from 
22d50 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
22d60 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20  s.** might also 
22d70 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e  consider lowerin
22d80 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74  g resource limit
22d90 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  s using [sqlite3
22da0 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64  _limit()].** and
22db0 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61   limiting databa
22dc0 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68  se size using th
22dd0 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  e [max_page_coun
22de0 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69  t] [PRAGMA].** i
22df0 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73  n addition to us
22e00 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ing an authorize
22e10 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20  r..**.** ^(Only 
22e20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69  a single authori
22e30 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c  zer can be in pl
22e40 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73  ace on a databas
22e50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
22e60 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68  at a time.  Each
22e70 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
22e80 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
22e90 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a  overrides the.**
22ea0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29   previous call.)
22eb0 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20  ^  ^Disable the 
22ec0 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e  authorizer by in
22ed0 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20  stalling a NULL 
22ee0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65  callback..** The
22ef0 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64   authorizer is d
22f00 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
22f10 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75  lt..**.** The au
22f20 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
22f30 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
22f40 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
22f50 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
22f60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
22f70 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
22f80 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
22f90 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65  allback..** Note
22fa0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
22fb0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
22fc0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
22fd0 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
22fe0 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
22ff0 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
23000 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
23010 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
23020 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
23030 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f   ^When [sqlite3_
23040 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73  prepare_v2()] is
23050 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65   used to prepare
23060 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68   a statement, th
23070 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d  e.** statement m
23080 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61  ight be re-prepa
23090 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69  red during [sqli
230a0 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20  te3_step()] due 
230b0 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20  to a .** schema 
230c0 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20  change.  Hence, 
230d0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
230e0 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68  should ensure th
230f0 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63  at the.** correc
23100 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  t authorizer cal
23110 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e  lback remains in
23120 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68   place during th
23130 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
23140 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20  )]..**.** ^Note 
23150 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
23160 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
23170 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72  invoked only dur
23180 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
23190 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
231a0 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74  s variants.  Aut
231b0 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f  horization is no
231c0 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64  t.** performed d
231d0 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  uring statement 
231e0 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73  evaluation in [s
231f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
23200 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61  unless.** as sta
23210 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69  ted in the previ
23220 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73  ous paragraph, s
23230 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
23240 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33  vokes.** sqlite3
23250 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f  _prepare_v2() to
23260 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61   reprepare a sta
23270 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73  tement after a s
23280 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f  chema change..*/
23290 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
232a0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
232b0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
232c0 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33  rizer(.  sqlite3
232d0 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68  *,.  int (*xAuth
232e0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
232f0 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
23300 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
23310 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20  const char*),.  
23320 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a  void *pUserData.
23330 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
23340 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52  EF: Authorizer R
23350 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  eturn Codes.**.*
23360 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
23370 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
23380 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
23390 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75  ack function] mu
233a0 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74  st.** return eit
233b0 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  her [SQLITE_OK] 
233c0 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  or one of these 
233d0 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e  two constants in
233e0 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67   order.** to sig
233f0 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68  nal SQLite wheth
23400 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63  er or not the ac
23410 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
23420 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b  d.  See the.** [
23430 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
23440 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
23450 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  zer documentatio
23460 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  n] for additiona
23470 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
23480 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
23490 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  t SQLITE_IGNORE 
234a0 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20  is also used as 
234b0 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f  a [conflict reso
234c0 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20  lution mode].** 
234d0 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68  returned from th
234e0 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  e [sqlite3_vtab_
234f0 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69  on_conflict()] i
23500 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65  nterface..*/.#de
23510 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59  fine SQLITE_DENY
23520 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20     1   /* Abort 
23530 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
23540 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  t with an error 
23550 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23560 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20  E_IGNORE 2   /* 
23570 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65  Don't allow acce
23580 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65  ss, but don't ge
23590 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20  nerate an error 
235a0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
235b0 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41  EF: Authorizer A
235c0 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  ction Codes.**.*
235d0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
235e0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
235f0 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
23600 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  ters a callback 
23610 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  function.** that
23620 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61   is invoked to a
23630 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e  uthorize certain
23640 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
23650 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20  ctions.  The.** 
23660 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
23670 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
23680 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63   is an integer c
23690 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69  ode that specifi
236a0 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f  es.** what actio
236b0 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f  n is being autho
236c0 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72  rized.  These ar
236d0 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63  e the integer ac
236e0 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a  tion codes that.
236f0 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
23700 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62  r callback may b
23710 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  e passed..**.** 
23720 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64  These action cod
23730 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79  e values signify
23740 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70   what kind of op
23750 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  eration is to be
23760 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  .** authorized. 
23770 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68   The 3rd and 4th
23780 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
23790 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e  he authorization
237a0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
237b0 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61  ction will be pa
237c0 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c  rameters or NULL
237d0 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68   depending on wh
237e0 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ich of these.** 
237f0 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73  codes is used as
23800 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
23810 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74  meter.  ^(The 5t
23820 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
23830 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
23840 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
23850 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
23860 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22  abase ("main", "
23870 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20  temp",.** etc.) 
23880 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e  if applicable.)^
23890 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d    ^The 6th param
238a0 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
238b0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a  orizer callback.
238c0 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
238d0 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74  f the inner-most
238e0 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77   trigger or view
238f0 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73   that is respons
23900 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  ible for.** the 
23910 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f  access attempt o
23920 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61  r NULL if this a
23930 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73  ccess attempt is
23940 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a   directly from.*
23950 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20  * top-level SQL 
23960 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a  code..*/./******
23970 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
23980 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
23990 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a  ***** 3rd ******
239a0 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a  ****** 4th *****
239b0 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20  ******/.#define 
239c0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e  SQLITE_CREATE_IN
239d0 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20  DEX          1  
239e0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
239f0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
23a00 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
23a10 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42  QLITE_CREATE_TAB
23a20 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20  LE          2   
23a30 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
23a40 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
23a50 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
23a60 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
23a70 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f  _INDEX     3   /
23a80 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
23a90 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
23aa0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
23ab0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
23ac0 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a  TABLE     4   /*
23ad0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
23ae0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
23af0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
23b00 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
23b10 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20  RIGGER   5   /* 
23b20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
23b30 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
23b40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23b50 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49  E_CREATE_TEMP_VI
23b60 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56  EW      6   /* V
23b70 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
23b80 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
23b90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
23ba0 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20  _CREATE_TRIGGER 
23bb0 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72         7   /* Tr
23bc0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
23bd0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
23be0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23bf0 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20  CREATE_VIEW     
23c00 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65        8   /* Vie
23c10 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
23c20 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
23c30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
23c40 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20  ELETE           
23c50 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c       9   /* Tabl
23c60 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
23c70 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
23c80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
23c90 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  OP_INDEX        
23ca0 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78     10   /* Index
23cb0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
23cc0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
23cd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
23ce0 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  P_TABLE         
23cf0 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20    11   /* Table 
23d00 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
23d10 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
23d20 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
23d30 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
23d40 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   12   /* Index N
23d50 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
23d60 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
23d70 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
23d80 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20  TEMP_TABLE      
23d90 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  13   /* Table Na
23da0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
23db0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
23dc0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
23dd0 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31  EMP_TRIGGER    1
23de0 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  4   /* Trigger N
23df0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
23e00 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
23e10 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
23e20 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35  MP_VIEW       15
23e30 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
23e40 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
23e50 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
23e60 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49   SQLITE_DROP_TRI
23e70 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20  GGER         16 
23e80 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
23e90 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
23ea0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
23eb0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57  SQLITE_DROP_VIEW
23ec0 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20              17  
23ed0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
23ee0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
23ef0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
23f00 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20  QLITE_INSERT    
23f10 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20             18   
23f20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
23f30 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
23f40 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
23f50 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20  LITE_PRAGMA     
23f60 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f            19   /
23f70 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20  * Pragma Name   
23f80 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c    1st arg or NUL
23f90 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  L */.#define SQL
23fa0 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20  ITE_READ        
23fb0 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a           20   /*
23fc0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
23fd0 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
23fe0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
23ff0 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  TE_SELECT       
24000 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20          21   /* 
24010 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
24020 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
24030 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
24040 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20  E_TRANSACTION   
24050 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f         22   /* O
24060 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e  peration       N
24070 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
24080 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
24090 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20  _UPDATE         
240a0 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61        23   /* Ta
240b0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
240c0 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
240d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
240e0 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20  ATTACH          
240f0 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c       24   /* Fil
24100 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c  ename        NUL
24110 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
24120 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
24130 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  ETACH           
24140 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61      25   /* Data
24150 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c  base Name   NULL
24160 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
24170 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c  define SQLITE_AL
24180 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20  TER_TABLE       
24190 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62     26   /* Datab
241a0 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65  ase Name   Table
241b0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
241c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49  efine SQLITE_REI
241d0 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20  NDEX            
241e0 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20    27   /* Index 
241f0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
24200 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
24210 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c  fine SQLITE_ANAL
24220 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  YZE             
24230 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   28   /* Table N
24240 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
24250 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
24260 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
24270 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  E_VTABLE        
24280 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  29   /* Table Na
24290 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
242a0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
242b0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
242c0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33  TABLE          3
242d0 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
242e0 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
242f0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
24300 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f  e SQLITE_FUNCTIO
24310 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31  N             31
24320 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
24330 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e        Function N
24340 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  ame   */.#define
24350 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e   SQLITE_SAVEPOIN
24360 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20  T            32 
24370 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
24380 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e       Savepoint N
24390 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ame  */.#define 
243a0 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20  SQLITE_COPY     
243b0 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20               0  
243c0 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73   /* No longer us
243d0 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
243e0 4c 49 54 45 5f 52 45 43 55 52 53 49 56 45 20 20  LITE_RECURSIVE  
243f0 20 20 20 20 20 20 20 20 20 20 33 33 20 20 20 2f            33   /
24400 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
24410 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
24420 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    */../*.** CAPI
24430 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e  3REF: Tracing An
24440 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63  d Profiling Func
24450 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  tions.** METHOD:
24460 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54   sqlite3.**.** T
24470 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
24480 65 20 64 65 70 72 65 63 61 74 65 64 2e 20 55 73  e deprecated. Us
24490 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  e the [sqlite3_t
244a0 72 61 63 65 5f 76 32 28 29 5d 20 69 6e 74 65 72  race_v2()] inter
244b0 66 61 63 65 0a 2a 2a 20 69 6e 73 74 65 61 64 20  face.** instead 
244c0 6f 66 20 74 68 65 20 72 6f 75 74 69 6e 65 73 20  of the routines 
244d0 64 65 73 63 72 69 62 65 64 20 68 65 72 65 2e 0a  described here..
244e0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
244f0 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61  ines register ca
24500 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73  llback functions
24510 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65   that can be use
24520 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67  d for.** tracing
24530 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74   and profiling t
24540 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  he execution of 
24550 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
24560 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
24570 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
24580 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
24590 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e  e3_trace() is in
245a0 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69  voked at.** vari
245b0 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61  ous times when a
245c0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
245d0 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20  is being run by 
245e0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
245f0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
24600 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61  3_trace() callba
24610 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69  ck is invoked wi
24620 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65  th a UTF-8 rende
24630 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53  ring of the.** S
24640 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
24650 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65  t as the stateme
24660 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20  nt first begins 
24670 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28  executing..** ^(
24680 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74  Additional sqlit
24690 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
246a0 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72  acks might occur
246b0 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67  .** as each trig
246c0 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d  gered subprogram
246d0 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68   is entered.  Th
246e0 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20  e callbacks for 
246f0 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74  triggers.** cont
24700 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20  ain a UTF-8 SQL 
24710 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65  comment that ide
24720 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67  ntifies the trig
24730 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ger.)^.**.** The
24740 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53   [SQLITE_TRACE_S
24750 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69  IZE_LIMIT] compi
24760 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63  le-time option c
24770 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69  an be used to li
24780 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74  mit.** the lengt
24790 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61  h of [bound para
247a0 6d 65 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e  meter] expansion
247b0 20 69 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f   in the output o
247c0 66 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  f sqlite3_trace(
247d0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  )..**.** ^The ca
247e0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
247f0 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
24800 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
24810 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73  is invoked.** as
24820 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
24830 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e  ent finishes.  ^
24840 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
24850 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  back contains.**
24860 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
24870 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64  atement text and
24880 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20   an estimate of 
24890 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a  wall-clock time.
248a0 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74  ** of how long t
248b0 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  hat statement to
248c0 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65  ok to run.  ^The
248d0 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
248e0 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20  k.** time is in 
248f0 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63  units of nanosec
24900 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68  onds, however th
24910 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d  e current implem
24920 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f  entation.** is o
24930 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d  nly capable of m
24940 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c  illisecond resol
24950 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78  ution so the six
24960 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61   least significa
24970 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20  nt.** digits in 
24980 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61  the time are mea
24990 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72  ningless.  Futur
249a0 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
249b0 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72  Lite.** might pr
249c0 6f 76 69 64 65 20 67 72 65 61 74 65 72 20 72 65  ovide greater re
249d0 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20  solution on the 
249e0 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63  profiler callbac
249f0 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74  k.  The.** sqlit
24a00 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e  e3_profile() fun
24a10 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65  ction is conside
24a20 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  red experimental
24a30 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65   and is.** subje
24a40 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20  ct to change in 
24a50 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
24a60 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51  of SQLite..*/.SQ
24a70 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
24a80 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20  DEPRECATED void 
24a90 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
24aa0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71  sqlite3_trace(sq
24ab0 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28  lite3*,.   void(
24ac0 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63  *xTrace)(void*,c
24ad0 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69  onst char*), voi
24ae0 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  d*);.SQLITE_API 
24af0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
24b00 44 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53  D void *SQLITE_S
24b10 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70  TDCALL sqlite3_p
24b20 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c  rofile(sqlite3*,
24b30 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69  .   void(*xProfi
24b40 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  le)(void*,const 
24b50 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69  char*,sqlite3_ui
24b60 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  nt64), void*);..
24b70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
24b80 53 51 4c 20 54 72 61 63 65 20 45 76 65 6e 74 20  SQL Trace Event 
24b90 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  Codes.** KEYWORD
24ba0 53 3a 20 53 51 4c 49 54 45 5f 54 52 41 43 45 0a  S: SQLITE_TRACE.
24bb0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
24bc0 74 61 6e 74 73 20 69 64 65 6e 74 69 66 79 20 63  tants identify c
24bd0 6c 61 73 73 65 73 20 6f 66 20 65 76 65 6e 74 73  lasses of events
24be0 20 74 68 61 74 20 63 61 6e 20 62 65 20 6d 6f 6e   that can be mon
24bf0 69 74 6f 72 65 64 0a 2a 2a 20 75 73 69 6e 67 20  itored.** using 
24c00 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72 61  the [sqlite3_tra
24c10 63 65 5f 76 32 28 29 5d 20 74 72 61 63 69 6e 67  ce_v2()] tracing
24c20 20 6c 6f 67 69 63 2e 20 20 54 68 65 20 74 68 69   logic.  The thi
24c30 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  rd argument.** t
24c40 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65  o [sqlite3_trace
24c50 5f 76 32 28 29 5d 20 69 73 20 61 6e 20 4f 52 2d  _v2()] is an OR-
24c60 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f  ed combination o
24c70 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  f one or more of
24c80 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** the followin
24c90 67 20 63 6f 6e 73 74 61 6e 74 73 2e 20 20 5e 54  g constants.  ^T
24ca0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
24cb0 74 20 74 6f 20 74 68 65 20 74 72 61 63 65 20 63  t to the trace c
24cc0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6f 6e  allback.** is on
24cd0 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
24ce0 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a  ng constants..**
24cf0 0a 2a 2a 20 4e 65 77 20 74 72 61 63 69 6e 67 20  .** New tracing 
24d00 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65  constants may be
24d10 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
24d20 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a   releases..**.**
24d30 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61   ^A trace callba
24d40 63 6b 20 68 61 73 20 66 6f 75 72 20 61 72 67 75  ck has four argu
24d50 6d 65 6e 74 73 3a 20 78 43 61 6c 6c 62 61 63 6b  ments: xCallback
24d60 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54  (T,C,P,X)..** ^T
24d70 68 65 20 54 20 61 72 67 75 6d 65 6e 74 20 69 73  he T argument is
24d80 20 6f 6e 65 20 6f 66 20 74 68 65 20 69 6e 74 65   one of the inte
24d90 67 65 72 20 74 79 70 65 20 63 6f 64 65 73 20 61  ger type codes a
24da0 62 6f 76 65 2e 0a 2a 2a 20 5e 54 68 65 20 43 20  bove..** ^The C 
24db0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 63 6f  argument is a co
24dc0 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 78  py of the contex
24dd0 74 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64  t pointer passed
24de0 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f   in as the.** fo
24df0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
24e00 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f   [sqlite3_trace_
24e10 76 32 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 50 20  v2()]..** The P 
24e20 61 6e 64 20 58 20 61 72 67 75 6d 65 6e 74 73 20  and X arguments 
24e30 61 72 65 20 70 6f 69 6e 74 65 72 73 20 77 68 6f  are pointers who
24e40 73 65 20 6d 65 61 6e 69 6e 67 73 20 64 65 70 65  se meanings depe
24e50 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 3c  nd on T..**.** <
24e60 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  dl>.** [[SQLITE_
24e70 54 52 41 43 45 5f 53 54 4d 54 5d 5d 20 3c 64 74  TRACE_STMT]] <dt
24e80 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54  >SQLITE_TRACE_ST
24e90 4d 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e  MT</dt>.** <dd>^
24ea0 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  An SQLITE_TRACE_
24eb0 53 54 4d 54 20 63 61 6c 6c 62 61 63 6b 20 69 73  STMT callback is
24ec0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20   invoked when a 
24ed0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24ee0 6e 74 0a 2a 2a 20 66 69 72 73 74 20 62 65 67 69  nt.** first begi
24ef0 6e 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 70  ns running and p
24f00 6f 73 73 69 62 6c 79 20 61 74 20 6f 74 68 65 72  ossibly at other
24f10 20 74 69 6d 65 73 20 64 75 72 69 6e 67 20 74 68   times during th
24f20 65 0a 2a 2a 20 65 78 65 63 75 74 69 6f 6e 20 6f  e.** execution o
24f30 66 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  f the prepared s
24f40 74 61 74 65 6d 65 6e 74 2c 20 73 75 63 68 20 61  tatement, such a
24f50 73 20 61 74 20 74 68 65 20 73 74 61 72 74 20 6f  s at the start o
24f60 66 20 65 61 63 68 0a 2a 2a 20 74 72 69 67 67 65  f each.** trigge
24f70 72 20 73 75 62 70 72 6f 67 72 61 6d 2e 20 5e 54  r subprogram. ^T
24f80 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73  he P argument is
24f90 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
24fa0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
24fb0 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 65 20  tatement]. ^The 
24fc0 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  X argument is a 
24fd0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72  pointer to a str
24fe0 69 6e 67 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ing which.** is 
24ff0 74 68 65 20 75 6e 65 78 70 61 6e 64 65 64 20 53  the unexpanded S
25000 51 4c 20 74 65 78 74 20 6f 66 20 74 68 65 20 70  QL text of the p
25010 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25020 74 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d  t or an SQL comm
25030 65 6e 74 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64  ent .** that ind
25040 69 63 61 74 65 73 20 74 68 65 20 69 6e 76 6f 63  icates the invoc
25050 61 74 69 6f 6e 20 6f 66 20 61 20 74 72 69 67 67  ation of a trigg
25060 65 72 2e 20 20 5e 54 68 65 20 63 61 6c 6c 62 61  er.  ^The callba
25070 63 6b 20 63 61 6e 20 63 6f 6d 70 75 74 65 0a 2a  ck can compute.*
25080 2a 20 74 68 65 20 73 61 6d 65 20 74 65 78 74 20  * the same text 
25090 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 20  that would have 
250a0 62 65 65 6e 20 72 65 74 75 72 6e 65 64 20 62 79  been returned by
250b0 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c   the legacy [sql
250c0 69 74 65 33 5f 74 72 61 63 65 28 29 5d 0a 2a 2a  ite3_trace()].**
250d0 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 75 73   interface by us
250e0 69 6e 67 20 74 68 65 20 58 20 61 72 67 75 6d 65  ing the X argume
250f0 6e 74 20 77 68 65 6e 20 58 20 62 65 67 69 6e 73  nt when X begins
25100 20 77 69 74 68 20 22 2d 2d 22 20 61 6e 64 20 69   with "--" and i
25110 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  nvoking.** [sqli
25120 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c  te3_expanded_sql
25130 28 50 29 5d 20 6f 74 68 65 72 77 69 73 65 2e 0a  (P)] otherwise..
25140 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54  **.** [[SQLITE_T
25150 52 41 43 45 5f 50 52 4f 46 49 4c 45 5d 5d 20 3c  RACE_PROFILE]] <
25160 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  dt>SQLITE_TRACE_
25170 50 52 4f 46 49 4c 45 3c 2f 64 74 3e 0a 2a 2a 20  PROFILE</dt>.** 
25180 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54  <dd>^An SQLITE_T
25190 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c  RACE_PROFILE cal
251a0 6c 62 61 63 6b 20 70 72 6f 76 69 64 65 73 20 61  lback provides a
251b0 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 74 68 65  pproximately the
251c0 20 73 61 6d 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61   same.** informa
251d0 74 69 6f 6e 20 61 73 20 69 73 20 70 72 6f 76 69  tion as is provi
251e0 64 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ded by the [sqli
251f0 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20 63  te3_profile()] c
25200 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65  allback..** ^The
25210 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61   P argument is a
25220 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
25230 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
25240 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20  ent] and the.** 
25250 58 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  X argument point
25260 73 20 74 6f 20 61 20 36 34 2d 62 69 74 20 69 6e  s to a 64-bit in
25270 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 74  teger which is t
25280 68 65 20 65 73 74 69 6d 61 74 65 64 20 6f 66 0a  he estimated of.
25290 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
252a0 20 6e 61 6e 6f 73 65 63 6f 6e 64 20 74 68 61 74   nanosecond that
252b0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
252c0 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20  atement took to 
252d0 72 75 6e 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c  run..** ^The SQL
252e0 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c  ITE_TRACE_PROFIL
252f0 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  E callback is in
25300 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 73  voked when the s
25310 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65  tatement finishe
25320 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  s..**.** [[SQLIT
25330 45 5f 54 52 41 43 45 5f 52 4f 57 5d 5d 20 3c 64  E_TRACE_ROW]] <d
25340 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52  t>SQLITE_TRACE_R
25350 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e  OW</dt>.** <dd>^
25360 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  An SQLITE_TRACE_
25370 52 4f 57 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ROW callback is 
25380 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
25390 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73   a prepared.** s
253a0 74 61 74 65 6d 65 6e 74 20 67 65 6e 65 72 61 74  tatement generat
253b0 65 73 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20  es a single row 
253c0 6f 66 20 72 65 73 75 6c 74 2e 20 20 0a 2a 2a 20  of result.  .** 
253d0 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20  ^The P argument 
253e0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
253f0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
25400 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65  atement] and the
25410 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 69  .** X argument i
25420 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s unused..**.** 
25430 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43  [[SQLITE_TRACE_C
25440 4c 4f 53 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  LOSE]] <dt>SQLIT
25450 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 3c 2f 64  E_TRACE_CLOSE</d
25460 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51  t>.** <dd>^An SQ
25470 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45  LITE_TRACE_CLOSE
25480 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
25490 6f 6b 65 64 20 77 68 65 6e 20 61 20 64 61 74 61  oked when a data
254a0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
254b0 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 5e 54  on closes..** ^T
254c0 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73  he P argument is
254d0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
254e0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
254f0 65 63 74 69 6f 6e 5d 20 6f 62 6a 65 63 74 0a 2a  ection] object.*
25500 2a 20 61 6e 64 20 74 68 65 20 58 20 61 72 67 75  * and the X argu
25510 6d 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a  ment is unused..
25520 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
25530 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45  ine SQLITE_TRACE
25540 5f 53 54 4d 54 20 20 20 20 20 20 20 30 78 30 31  _STMT       0x01
25550 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
25560 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 20 20  TRACE_PROFILE   
25570 20 30 78 30 32 0a 23 64 65 66 69 6e 65 20 53 51   0x02.#define SQ
25580 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20 20  LITE_TRACE_ROW  
25590 20 20 20 20 20 20 30 78 30 34 0a 23 64 65 66 69        0x04.#defi
255a0 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  ne SQLITE_TRACE_
255b0 43 4c 4f 53 45 20 20 20 20 20 20 30 78 30 38 0a  CLOSE      0x08.
255c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
255d0 20 53 51 4c 20 54 72 61 63 65 20 48 6f 6f 6b 0a   SQL Trace Hook.
255e0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
255f0 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e3.**.** ^The sq
25600 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 44  lite3_trace_v2(D
25610 2c 4d 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63  ,M,X,P) interfac
25620 65 20 72 65 67 69 73 74 65 72 73 20 61 20 74 72  e registers a tr
25630 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ace callback.** 
25640 66 75 6e 63 74 69 6f 6e 20 58 20 61 67 61 69 6e  function X again
25650 73 74 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  st [database con
25660 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 75 73 69 6e  nection] D, usin
25670 67 20 70 72 6f 70 65 72 74 79 20 6d 61 73 6b 20  g property mask 
25680 4d 0a 2a 2a 20 61 6e 64 20 63 6f 6e 74 65 78 74  M.** and context
25690 20 70 6f 69 6e 74 65 72 20 50 2e 20 20 5e 49 66   pointer P.  ^If
256a0 20 74 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20   the X callback 
256b0 69 73 0a 2a 2a 20 4e 55 4c 4c 20 6f 72 20 69 66  is.** NULL or if
256c0 20 74 68 65 20 4d 20 6d 61 73 6b 20 69 73 20 7a   the M mask is z
256d0 65 72 6f 2c 20 74 68 65 6e 20 74 72 61 63 69 6e  ero, then tracin
256e0 67 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20  g is disabled.  
256f0 54 68 65 0a 2a 2a 20 4d 20 61 72 67 75 6d 65 6e  The.** M argumen
25700 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20  t should be the 
25710 62 69 74 77 69 73 65 20 4f 52 2d 65 64 20 63 6f  bitwise OR-ed co
25720 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  mbination of.** 
25730 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 5b 53 51  zero or more [SQ
25740 4c 49 54 45 5f 54 52 41 43 45 5d 20 63 6f 6e 73  LITE_TRACE] cons
25750 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 45 61  tants..**.** ^Ea
25760 63 68 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65  ch call to eithe
25770 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  r sqlite3_trace(
25780 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61  ) or sqlite3_tra
25790 63 65 5f 76 32 28 29 20 6f 76 65 72 72 69 64 65  ce_v2() override
257a0 73 20 0a 2a 2a 20 28 63 61 6e 63 65 6c 73 29 20  s .** (cancels) 
257b0 61 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20  any prior calls 
257c0 74 6f 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  to sqlite3_trace
257d0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72  () or sqlite3_tr
257e0 61 63 65 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  ace_v2()..**.** 
257f0 5e 54 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20  ^The X callback 
25800 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  is invoked whene
25810 76 65 72 20 61 6e 79 20 6f 66 20 74 68 65 20 65  ver any of the e
25820 76 65 6e 74 73 20 69 64 65 6e 74 69 66 69 65 64  vents identified
25830 20 62 79 20 0a 2a 2a 20 6d 61 73 6b 20 4d 20 6f   by .** mask M o
25840 63 63 75 72 2e 20 20 5e 54 68 65 20 69 6e 74 65  ccur.  ^The inte
25850 67 65 72 20 72 65 74 75 72 6e 20 76 61 6c 75 65  ger return value
25860 20 66 72 6f 6d 20 74 68 65 20 63 61 6c 6c 62 61   from the callba
25870 63 6b 20 69 73 20 63 75 72 72 65 6e 74 6c 79 0a  ck is currently.
25880 2a 2a 20 69 67 6e 6f 72 65 64 2c 20 74 68 6f 75  ** ignored, thou
25890 67 68 20 74 68 69 73 20 6d 61 79 20 63 68 61 6e  gh this may chan
258a0 67 65 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ge in future rel
258b0 65 61 73 65 73 2e 20 20 43 61 6c 6c 62 61 63 6b  eases.  Callback
258c0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
258d0 6f 6e 73 20 73 68 6f 75 6c 64 20 72 65 74 75 72  ons should retur
258e0 6e 20 7a 65 72 6f 20 74 6f 20 65 6e 73 75 72 65  n zero to ensure
258f0 20 66 75 74 75 72 65 20 63 6f 6d 70 61 74 69 62   future compatib
25900 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20  ility..**.** ^A 
25910 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69  trace callback i
25920 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 66  s invoked with f
25930 6f 75 72 20 61 72 67 75 6d 65 6e 74 73 3a 20 63  our arguments: c
25940 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29  allback(T,C,P,X)
25950 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72 67 75  ..** ^The T argu
25960 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 74  ment is one of t
25970 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  he [SQLITE_TRACE
25980 5d 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20 74  ].** constants t
25990 6f 20 69 6e 64 69 63 61 74 65 20 77 68 79 20 74  o indicate why t
259a0 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 61 73 20  he callback was 
259b0 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65  invoked..** ^The
259c0 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61   C argument is a
259d0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e   copy of the con
259e0 74 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  text pointer..**
259f0 20 54 68 65 20 50 20 61 6e 64 20 58 20 61 72 67   The P and X arg
25a00 75 6d 65 6e 74 73 20 61 72 65 20 70 6f 69 6e 74  uments are point
25a10 65 72 73 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e  ers whose meanin
25a20 67 73 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a  gs depend on T..
25a30 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
25a40 33 5f 74 72 61 63 65 5f 76 32 28 29 20 69 6e 74  3_trace_v2() int
25a50 65 72 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64  erface is intend
25a60 65 64 20 74 6f 20 72 65 70 6c 61 63 65 20 74 68  ed to replace th
25a70 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
25a80 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
25a90 74 72 61 63 65 28 29 5d 20 61 6e 64 20 5b 73 71  trace()] and [sq
25aa0 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d  lite3_profile()]
25ab0 2c 20 62 6f 74 68 20 6f 66 20 77 68 69 63 68 0a  , both of which.
25ac0 2a 2a 20 61 72 65 20 64 65 70 72 65 63 61 74 65  ** are deprecate
25ad0 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  d..*/.SQLITE_API
25ae0 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
25af0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74 72 61 63  ALL sqlite3_trac
25b00 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a  e_v2(.  sqlite3*
25b10 2c 0a 20 20 75 6e 73 69 67 6e 65 64 20 75 4d 61  ,.  unsigned uMa
25b20 73 6b 2c 0a 20 20 69 6e 74 28 2a 78 43 61 6c 6c  sk,.  int(*xCall
25b30 62 61 63 6b 29 28 75 6e 73 69 67 6e 65 64 2c 76  back)(unsigned,v
25b40 6f 69 64 2a 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a  oid*,void*,void*
25b50 29 2c 0a 20 20 76 6f 69 64 20 2a 70 43 74 78 0a  ),.  void *pCtx.
25b60 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
25b70 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65  EF: Query Progre
25b80 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20  ss Callbacks.** 
25b90 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
25ba0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
25bb0 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
25bc0 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74  ler(D,N,X,P) int
25bd0 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68  erface causes th
25be0 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  e callback.** fu
25bf0 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69  nction X to be i
25c00 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61  nvoked periodica
25c10 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20  lly during long 
25c20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
25c30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  .** [sqlite3_exe
25c40 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  c()], [sqlite3_s
25c50 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tep()] and [sqli
25c60 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
25c70 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65   for.** database
25c80 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20   connection D.  
25c90 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66  An example use f
25ca0 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72  or this.** inter
25cb0 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20  face is to keep 
25cc0 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75  a GUI updated du
25cd0 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65  ring a large que
25ce0 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ry..**.** ^The p
25cf0 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61  arameter P is pa
25d00 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
25d10 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
25d20 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61  er to the .** ca
25d30 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
25d40 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74  X.  ^The paramet
25d50 65 72 20 4e 20 69 73 20 74 68 65 20 61 70 70 72  er N is the appr
25d60 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f  oximate number o
25d70 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d  f .** [virtual m
25d80 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69  achine instructi
25d90 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76  ons] that are ev
25da0 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20  aluated between 
25db0 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e  successive.** in
25dc0 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
25dd0 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49   callback X.  ^I
25de0 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e  f N is less than
25df0 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70 72   one then the pr
25e00 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65  ogress.** handle
25e10 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a  r is disabled..*
25e20 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e  *.** ^Only a sin
25e30 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  gle progress han
25e40 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 69  dler may be defi
25e50 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20  ned at one time 
25e60 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  per.** [database
25e70 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65   connection]; se
25e80 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67  tting a new prog
25e90 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e  ress handler can
25ea0 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20  cels the.** old 
25eb0 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70  one.  ^Setting p
25ec0 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55  arameter X to NU
25ed0 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  LL disables the 
25ee0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
25ef0 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65  ..** ^The progre
25f00 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c  ss handler is al
25f10 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 73  so disabled by s
25f20 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61  etting N to a va
25f30 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e  lue less.** than
25f40 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68   1..**.** ^If th
25f50 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
25f60 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
25f70 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74  zero, the operat
25f80 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72  ion is.** interr
25f90 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61  upted.  This fea
25fa0 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64  ture can be used
25fb0 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a   to implement a.
25fc0 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74  ** "Cancel" butt
25fd0 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67  on on a GUI prog
25fe0 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e  ress dialog box.
25ff0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72  .**.** The progr
26000 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  ess handler call
26010 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f  back must not do
26020 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
26030 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
26040 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
26050 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
26060 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  ed the progress 
26070 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65  handler..** Note
26080 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
26090 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
260a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
260b0 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
260c0 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
260d0 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
260e0 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
260f0 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
26100 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f  paragraph..**.*/
26110 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
26120 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
26130 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
26140 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
26150 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76  *, int, int(*)(v
26160 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  oid*), void*);..
26170 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
26180 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61  Opening A New Da
26190 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
261a0 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52  n.** CONSTRUCTOR
261b0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
261c0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
261d0 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64  open an SQLite d
261e0 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20  atabase file as 
261f0 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
26200 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72   .** filename ar
26210 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c  gument. ^The fil
26220 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69  ename argument i
26230 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
26240 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71   UTF-8 for.** sq
26250 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
26260 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
26270 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36  () and as UTF-16
26280 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
26290 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72  yte.** order for
262a0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
262b0 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65  ). ^(A [database
262c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
262d0 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a  dle is usually.*
262e0 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70  * returned in *p
262f0 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20  pDb, even if an 
26300 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54  error occurs.  T
26310 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f  he only exceptio
26320 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20  n is that.** if 
26330 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
26340 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
26350 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
26360 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
26370 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c  ,.** a NULL will
26380 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   be written into
26390 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f   *ppDb instead o
263a0 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  f a pointer to t
263b0 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20  he [sqlite3].** 
263c0 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74  object.)^ ^(If t
263d0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
263e0 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72  pened (and/or cr
263f0 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75  eated) successfu
26400 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51  lly, then.** [SQ
26410 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
26420 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rned.  Otherwise
26430 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
26440 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
26450 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ^The.** [sqlite3
26460 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73  _errmsg()] or [s
26470 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
26480 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20  )] routines can 
26490 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
264a0 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20  n.** an English 
264b0 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70  language descrip
264c0 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f  tion of the erro
264d0 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61  r following a fa
264e0 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20  ilure of any.** 
264f0 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f  of the sqlite3_o
26500 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a  pen() routines..
26510 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
26520 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c  lt encoding will
26530 20 62 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61   be UTF-8 for da
26540 74 61 62 61 73 65 73 20 63 72 65 61 74 65 64 20  tabases created 
26550 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  using.** sqlite3
26560 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
26570 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e  e3_open_v2().  ^
26580 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f  The default enco
26590 64 69 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73  ding for databas
265a0 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73  es.** created us
265b0 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ing sqlite3_open
265c0 31 36 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46  16() will be UTF
265d0 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
265e0 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
265f0 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e  .** Whether or n
26600 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  ot an error occu
26610 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70  rs when it is op
26620 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a  ened, resources.
26630 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
26640 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
26650 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
26660 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65  dle should be re
26670 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73  leased by.** pas
26680 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
26690 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65  te3_close()] whe
266a0 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  n it is no longe
266b0 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  r required..**.*
266c0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  * The sqlite3_op
266d0 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  en_v2() interfac
266e0 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  e works like sql
266f0 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65  ite3_open().** e
26700 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63  xcept that it ac
26710 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69  cepts two additi
26720 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20  onal parameters 
26730 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63  for additional c
26740 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74  ontrol.** over t
26750 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
26760 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54  connection.  ^(T
26770 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
26780 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  er to.** sqlite3
26790 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74  _open_v2() can t
267a0 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68  ake one of.** th
267b0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65  e following thre
267c0 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e  e values, option
267d0 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
267e0 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  th the .** [SQLI
267f0 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
26800 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  , [SQLITE_OPEN_F
26810 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  ULLMUTEX], [SQLI
26820 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
26830 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  CHE],.** [SQLITE
26840 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
26850 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  HE], and/or [SQL
26860 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
26870 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  ags:)^.**.** <dl
26880 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  >.** ^(<dt>[SQLI
26890 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
268a0 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
268b0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
268c0 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c  ened in read-onl
268d0 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  y mode.  If the 
268e0 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f  database does no
268f0 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69  t.** already exi
26900 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20  st, an error is 
26910 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
26920 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
26930 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
26940 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ITE]</dt>.** <dd
26950 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
26960 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
26970 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20  ing and writing 
26980 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20  if possible, or 
26990 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20  reading.** only 
269a0 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77  if the file is w
269b0 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62  rite protected b
269c0 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  y the operating 
269d0 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68  system.  In eith
269e0 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64  er.** case the d
269f0 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72  atabase must alr
26a00 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65  eady exist, othe
26a10 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69  rwise an error i
26a20 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
26a30 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
26a40 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
26a50 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
26a60 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64  _OPEN_CREATE]</d
26a70 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
26a80 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
26a90 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
26aa0 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73   writing, and is
26ab0 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69   created if.** i
26ac0 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61  t does not alrea
26ad0 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69  dy exist. This i
26ae0 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74  s the behavior t
26af0 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73  hat is always us
26b00 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  ed for.** sqlite
26b10 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
26b20 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f  ite3_open16().</
26b30 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
26b40 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  *.** If the 3rd 
26b50 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
26b60 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
26b70 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65  s not one of the
26b80 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  .** combinations
26b90 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74   shown above opt
26ba0 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
26bb0 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b   with other.** [
26bc0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
26bd0 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50  ONLY | SQLITE_OP
26be0 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68  EN_* bits].** th
26bf0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
26c00 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
26c10 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  .** ^If the [SQL
26c20 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
26c30 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74  ] flag is set, t
26c40 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
26c50 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
26c60 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74  pens in the mult
26c70 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64  i-thread [thread
26c80 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e  ing mode] as lon
26c90 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d  g as the single-
26ca0 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68  thread.** mode h
26cb0 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20  as not been set 
26cc0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
26cd0 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20  or start-time.  
26ce0 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ^If the.** [SQLI
26cf0 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
26d00 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74  X] flag is set t
26d10 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
26d20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e   connection open
26d30 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69  s.** in the seri
26d40 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
26d50 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73  g mode] unless s
26d60 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73  ingle-thread was
26d70 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
26d80 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69  elected at compi
26d90 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
26da0 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b  -time..** ^The [
26db0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
26dc0 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  EDCACHE] flag ca
26dd0 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
26de0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
26df0 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74  be.** eligible t
26e00 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61  o use [shared ca
26e10 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72  che mode], regar
26e20 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
26e30 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a   or not shared.*
26e40 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c  * cache is enabl
26e50 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
26e60 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
26e70 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a  cache()].  ^The.
26e80 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
26e90 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c  PRIVATECACHE] fl
26ea0 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
26eb0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
26ec0 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74  n to not.** part
26ed0 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72  icipate in [shar
26ee0 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65  ed cache mode] e
26ef0 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61  ven if it is ena
26f00 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
26f10 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
26f20 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
26f30 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61  n_v2() is the na
26f40 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  me of the.** [sq
26f50 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
26f60 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74  t that defines t
26f70 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
26f80 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
26f90 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61  at.** the new da
26fa0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
26fb0 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e  n should use.  ^
26fc0 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
26fd0 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20  rameter is.** a 
26fe0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
26ff0 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  n the default [s
27000 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
27010 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  ct is used..**.*
27020 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
27030 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22  me is ":memory:"
27040 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
27050 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d  , temporary in-m
27060 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a  emory database.*
27070 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72  * is created for
27080 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e   the connection.
27090 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72    ^This in-memor
270a0 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  y database will 
270b0 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74  vanish when.** t
270c0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
270d0 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
270e0 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
270f0 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
27100 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f  ht.** make use o
27110 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65  f additional spe
27120 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74  cial filenames t
27130 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74  hat begin with t
27140 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72  he ":" character
27150 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d  ..** It is recom
27160 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e  mended that when
27170 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
27180 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f  name actually do
27190 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a  es begin with.**
271a0 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72   a ":" character
271b0 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66   you should pref
271c0 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  ix the filename 
271d0 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20  with a pathname 
271e0 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20  such as.** "./" 
271f0 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69  to avoid ambigui
27200 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ty..**.** ^If th
27210 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e  e filename is an
27220 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74   empty string, t
27230 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
27240 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64  emporary.** on-d
27250 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c  isk database wil
27260 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e  l be created.  ^
27270 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74  This private dat
27280 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a  abase will be.**
27290 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
272a0 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  eleted as soon a
272b0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
272c0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
272d0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49  sed..**.** [[URI
272e0 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71   filenames in sq
272f0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c  lite3_open()]] <
27300 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73  h3>URI Filenames
27310 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  </h3>.**.** ^If 
27320 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69  [URI filename] i
27330 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
27340 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68   enabled, and th
27350 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
27360 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69  ent.** begins wi
27370 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e  th "file:", then
27380 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
27390 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
273a0 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66  a URI. ^URI.** f
273b0 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65  ilename interpre
273c0 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  tation is enable
273d0 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  d if the [SQLITE
273e0 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
273f0 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65  is.** set in the
27400 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
27410 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
27420 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20  _v2(), or if it 
27430 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62  has.** been enab
27440 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69  led globally usi
27450 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43  ng the [SQLITE_C
27460 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f  ONFIG_URI] optio
27470 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73  n with the.** [s
27480 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
27490 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68   method or by th
274a0 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  e [SQLITE_USE_UR
274b0 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  I] compile-time 
274c0 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66  option..** As of
274d0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
274e0 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e  3.7.7, URI filen
274f0 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69  ame interpretati
27500 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66  on is turned off
27510 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20  .** by default, 
27520 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61  but future relea
27530 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ses of SQLite mi
27540 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66  ght enable URI f
27550 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72  ilename.** inter
27560 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66  pretation by def
27570 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49  ault.  See "[URI
27580 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72   filenames]" for
27590 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
275a0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
275b0 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  * URI filenames 
275c0 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72  are parsed accor
275d0 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36  ding to RFC 3986
275e0 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f  . ^If the URI co
275f0 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74  ntains an.** aut
27600 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20  hority, then it 
27610 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61  must be either a
27620 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  n empty string o
27630 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a  r the string .**
27640 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49   "localhost". ^I
27650 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20  f the authority 
27660 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20  is not an empty 
27670 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c  string or "local
27680 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72  host", an .** er
27690 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
276a0 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e  to the caller. ^
276b0 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d  The fragment com
276c0 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c  ponent of a URI,
276d0 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c   if .** present,
276e0 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a   is ignored..**.
276f0 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
27700 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65  the path compone
27710 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73  nt of the URI as
27720 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
27730 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68   disk file.** wh
27740 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ich contains the
27750 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74   database. ^If t
27760 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77  he path begins w
27770 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63  ith a '/' charac
27780 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74  ter, .** then it
27790 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
277a0 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70  as an absolute p
277b0 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74  ath. ^If the pat
277c0 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e  h does not begin
277d0 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20   .** with a '/' 
277e0 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68  (meaning that th
277f0 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74  e authority sect
27800 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66  ion is omitted f
27810 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20  rom the URI).** 
27820 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73  then the path is
27830 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
27840 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e  a relative path.
27850 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77   .** ^(On window
27860 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d  s, the first com
27870 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73  ponent of an abs
27880 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69  olute path .** i
27890 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66  s a drive specif
278a0 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43  ication (e.g. "C
278b0 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63  :").)^.**.** [[c
278c0 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70 61  ore URI query pa
278d0 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68  rameters]].** Th
278e0 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  e query componen
278f0 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63  t of a URI may c
27900 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72  ontain parameter
27910 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72  s that are inter
27920 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72  preted.** either
27930 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c   by SQLite itsel
27940 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20  f, or by a [VFS 
27950 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70  | custom VFS imp
27960 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a  lementation]..**
27970 20 53 51 4c 69 74 65 20 61 6e 64 20 69 74 73 20   SQLite and its 
27980 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d  built-in [VFSes]
27990 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a   interpret the.*
279a0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72  * following quer
279b0 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a  y parameters:.**
279c0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  .** <ul>.**   <l
279d0 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e  i> <b>vfs</b>: ^
279e0 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d 65  The "vfs" parame
279f0 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20  ter may be used 
27a00 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 6e  to specify the n
27a10 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20  ame of.**     a 
27a20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20  VFS object that 
27a30 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65  provides the ope
27a40 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e  rating system in
27a50 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68 6f  terface that sho
27a60 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73  uld.**     be us
27a70 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ed to access the
27a80 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f   database file o
27a90 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73  n disk. ^If this
27aa0 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74   option is set t
27ab0 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74  o.**     an empt
27ac0 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 66  y string the def
27ad0 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20  ault VFS object 
27ae0 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66  is used. ^Specif
27af0 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a  ying an unknown.
27b00 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 6e  **     VFS is an
27b10 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69   error. ^If sqli
27b20 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
27b30 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 66   used and the vf
27b40 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20  s option is.**  
27b50 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e     present, then
27b60 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66 69   the VFS specifi
27b70 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e  ed by the option
27b80 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63   takes precedenc
27b90 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68  e over.**     th
27ba0 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  e value passed a
27bb0 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  s the fourth par
27bc0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
27bd0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
27be0 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64  **   <li> <b>mod
27bf0 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64  e</b>: ^(The mod
27c00 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
27c10 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
27c20 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20   "ro", "rw",.** 
27c30 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d      "rwc", or "m
27c40 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69  emory". Attempti
27c50 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20  ng to set it to 
27c60 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20  any other value 
27c70 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72  is.**     an err
27c80 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49  or)^. .**     ^I
27c90 66 20 22 72 6f 22 20 69 73 20 73 70 65 63 69 66  f "ro" is specif
27ca0 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61  ied, then the da
27cb0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
27cc0 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a   for read-only .
27cd0 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a  **     access, j
27ce0 75 73 74 20 61 73 20 69 66 20 74 68 65 20 5b 53  ust as if the [S
27cf0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
27d00 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65  NLY] flag had be
27d10 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a  en set in the .*
27d20 2a 20 20 20 20 20 74 68 69 72 64 20 61 72 67 75  *     third argu
27d30 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
27d40 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74  open_v2(). ^If t
27d50 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69  he mode option i
27d60 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20  s set to .**    
27d70 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20   "rw", then the 
27d80 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
27d90 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74  ed for read-writ
27da0 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74  e (but not creat
27db0 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73  e) .**     acces
27dc0 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f  s, as if SQLITE_
27dd0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28  OPEN_READWRITE (
27de0 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f  but not SQLITE_O
27df0 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20  PEN_CREATE) had 
27e00 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74  .**     been set
27e10 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69  . ^Value "rwc" i
27e20 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
27e30 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a  setting both .**
27e40 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
27e50 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20 53  _READWRITE and S
27e60 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
27e70 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65  E.  ^If the mode
27e80 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20   option is.**   
27e90 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79    set to "memory
27ea0 22 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69  " then a pure [i
27eb0 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
27ec0 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72 65  e] that never re
27ed0 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72  ads.**     or wr
27ee0 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69  ites from disk i
27ef0 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61  s used. ^It is a
27f00 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69  n error to speci
27f10 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a  fy a value for.*
27f20 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70  *     the mode p
27f30 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 73  arameter that is
27f40 20 6c 65 73 73 20 72 65 73 74 72 69 63 74 69 76   less restrictiv
27f50 65 20 74 68 61 6e 20 74 68 61 74 20 73 70 65 63  e than that spec
27f60 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  ified by.**     
27f70 74 68 65 20 66 6c 61 67 73 20 70 61 73 73 65 64  the flags passed
27f80 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61   in the third pa
27f90 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
27fa0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
27fb0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61  .**   <li> <b>ca
27fc0 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61  che</b>: ^The ca
27fd0 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  che parameter ma
27fe0 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68  y be set to eith
27ff0 65 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a  er "shared" or.*
28000 2a 20 20 20 20 20 22 70 72 69 76 61 74 65 22 2e  *     "private".
28010 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20   ^Setting it to 
28020 22 73 68 61 72 65 64 22 20 69 73 20 65 71 75 69  "shared" is equi
28030 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
28040 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c  g the.**     SQL
28050 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
28060 41 43 48 45 20 62 69 74 20 69 6e 20 74 68 65 20  ACHE bit in the 
28070 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70  flags argument p
28080 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20  assed to.**     
28090 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
280a0 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20  ). ^Setting the 
280b0 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20  cache parameter 
280c0 74 6f 20 22 70 72 69 76 61 74 65 22 20 69 73 20  to "private" is 
280d0 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65  .**     equivale
280e0 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68  nt to setting th
280f0 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52  e SQLITE_OPEN_PR
28100 49 56 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a  IVATECACHE bit..
28110 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74  **     ^If sqlit
28120 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
28130 75 73 65 64 20 61 6e 64 20 74 68 65 20 22 63 61  used and the "ca
28140 63 68 65 22 20 70 61 72 61 6d 65 74 65 72 20 69  che" parameter i
28150 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20  s present in.** 
28160 20 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61      a URI filena
28170 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76  me, its value ov
28180 65 72 72 69 64 65 73 20 61 6e 79 20 62 65 68 61  errides any beha
28190 76 69 6f 72 20 72 65 71 75 65 73 74 65 64 20 62  vior requested b
281a0 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20  y setting.**    
281b0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
281c0 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c  VATECACHE or SQL
281d0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
281e0 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a  ACHE flag..**.**
281f0 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f    <li> <b>psow</
28200 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 61  b>: ^The psow pa
28210 72 61 6d 65 74 65 72 20 69 6e 64 69 63 61 74 65  rameter indicate
28220 73 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  s whether or not
28230 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77   the.**     [pow
28240 65 72 73 61 66 65 20 6f 76 65 72 77 72 69 74 65  ersafe overwrite
28250 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65 73 20  ] property does 
28260 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c  or does not appl
28270 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20  y to the.**     
28280 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20 6f 6e  storage media on
28290 20 77 68 69 63 68 20 74 68 65 20 64 61 74 61 62   which the datab
282a0 61 73 65 20 66 69 6c 65 20 72 65 73 69 64 65 73  ase file resides
282b0 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62  ..**.**  <li> <b
282c0 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68  >nolock</b>: ^Th
282d0 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74  e nolock paramet
282e0 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20  er is a boolean 
282f0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 0a  query parameter.
28300 2a 2a 20 20 20 20 20 77 68 69 63 68 20 69 66 20  **     which if 
28310 73 65 74 20 64 69 73 61 62 6c 65 73 20 66 69 6c  set disables fil
28320 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c  e locking in rol
28330 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f  lback journal mo
28340 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20  des.  This.**   
28350 20 20 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20    is useful for 
28360 61 63 63 65 73 73 69 6e 67 20 61 20 64 61 74 61  accessing a data
28370 62 61 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 79  base on a filesy
28380 73 74 65 6d 20 74 68 61 74 20 64 6f 65 73 20 6e  stem that does n
28390 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f 72  ot.**     suppor
283a0 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74  t locking.  Caut
283b0 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 65 20 63  ion:  Database c
283c0 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20  orruption might 
283d0 72 65 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a  result if two.**
283e0 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f       or more pro
283f0 63 65 73 73 65 73 20 77 72 69 74 65 20 74 6f 20  cesses write to 
28400 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
28410 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66  e and any one of
28420 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72   those.**     pr
28430 6f 63 65 73 73 65 73 20 75 73 65 73 20 6e 6f 6c  ocesses uses nol
28440 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c  ock=1..**.**  <l
28450 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c  i> <b>immutable<
28460 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61  /b>: ^The immuta
28470 62 6c 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ble parameter is
28480 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79   a boolean query
28490 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65  .**     paramete
284a0 72 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73  r that indicates
284b0 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61   that the databa
284c0 73 65 20 66 69 6c 65 20 69 73 20 73 74 6f 72 65  se file is store
284d0 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64  d on.**     read
284e0 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57  -only media.  ^W
284f0 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 73  hen immutable is
28500 20 73 65 74 2c 20 53 51 4c 69 74 65 20 61 73 73   set, SQLite ass
28510 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
28520 20 20 20 20 20 64 61 74 61 62 61 73 65 20 66 69       database fi
28530 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61  le cannot be cha
28540 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 20 61 20  nged, even by a 
28550 70 72 6f 63 65 73 73 20 77 69 74 68 20 68 69 67  process with hig
28560 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 69  her.**     privi
28570 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 65  lege, and so the
28580 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
28590 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e  ned read-only an
285a0 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a  d all locking.**
285b0 20 20 20 20 20 61 6e 64 20 63 68 61 6e 67 65 20       and change 
285c0 64 65 74 65 63 74 69 6f 6e 20 69 73 20 64 69 73  detection is dis
285d0 61 62 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a  abled.  Caution:
285e0 20 53 65 74 74 69 6e 67 20 74 68 65 20 69 6d 6d   Setting the imm
285f0 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72  utable.**     pr
28600 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 61 74 61  operty on a data
28610 62 61 73 65 20 66 69 6c 65 20 74 68 61 74 20 64  base file that d
28620 6f 65 73 20 69 6e 20 66 61 63 74 20 63 68 61 6e  oes in fact chan
28630 67 65 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a  ge can result.**
28640 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 63       in incorrec
28650 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20  t query results 
28660 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43  and/or [SQLITE_C
28670 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a  ORRUPT] errors..
28680 2a 2a 20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a  **     See also:
28690 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49   [SQLITE_IOCAP_I
286a0 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20  MMUTABLE]..**   
286b0 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a      .** </ul>.**
286c0 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20  .** ^Specifying 
286d0 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d  an unknown param
286e0 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72  eter in the quer
286f0 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  y component of a
28700 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a   URI is not an.*
28710 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65  * error.  Future
28720 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
28730 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73  ite might unders
28740 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20  tand additional 
28750 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74  query.** paramet
28760 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72  ers.  See "[quer
28770 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74  y parameters wit
28780 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e  h special meanin
28790 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f  g to SQLite]" fo
287a0 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20  r.** additional 
287b0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
287c0 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ** [[URI filenam
287d0 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33  e examples]] <h3
287e0 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78  >URI filename ex
287f0 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a  amples</h3>.**.*
28800 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
28810 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72  "1" align=center
28820 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a   cellpadding=5>.
28830 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20  ** <tr><th> URI 
28840 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52  filenames <th> R
28850 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74  esults.** <tr><t
28860 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20  d> file:data.db 
28870 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
28880 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20    Open the file 
28890 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65  "data.db" in the
288a0 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f   current directo
288b0 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ry..** <tr><td> 
288c0 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f  file:/home/fred/
288d0 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20  data.db<br>.**  
288e0 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f          file:///
288f0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
28900 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20  b <br> .**      
28910 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c      file://local
28920 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  host/home/fred/d
28930 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e  ata.db <br> <td>
28940 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
28950 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
28960 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64  file "/home/fred
28970 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74  /data.db"..** <t
28980 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61  r><td> file://da
28990 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64  rkstar/home/fred
289a0 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a  /data.db <td> .*
289b0 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
289c0 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20  ror. "darkstar" 
289d0 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69  is not a recogni
289e0 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a  zed authority..*
289f0 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d  * <tr><td style=
28a00 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77  "white-space:now
28a10 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20  rap"> .**       
28a20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f     file:///C:/Do
28a30 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30  cuments%20and%20
28a40 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65  Settings/fred/De
28a50 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a  sktop/data.db.**
28a60 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77       <td> Window
28a70 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65  s only: Open the
28a80 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
28a90 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f  on fred's deskto
28aa0 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20  p on drive.**   
28ab0 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20         C:. Note 
28ac0 74 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63  that the %20 esc
28ad0 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78  aping in this ex
28ae0 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72  ample is not str
28af0 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20  ictly .**       
28b00 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73     necessary - s
28b10 70 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20  pace characters 
28b20 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65  can be used lite
28b30 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  rally.**        
28b40 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d    in URI filenam
28b50 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  es..** <tr><td> 
28b60 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64  file:data.db?mod
28b70 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61  e=ro&cache=priva
28b80 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  te <td> .**     
28b90 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22       Open file "
28ba0 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20  data.db" in the 
28bb0 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72  current director
28bc0 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20  y for read-only 
28bd0 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20  access..**      
28be0 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f      Regardless o
28bf0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
28c00 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f   shared-cache mo
28c10 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79  de is enabled by
28c20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66  .**          def
28c30 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76  ault, use a priv
28c40 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74  ate cache..** <t
28c50 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d  r><td> file:/hom
28c60 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76  e/fred/data.db?v
28c70 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20  fs=unix-dotfile 
28c80 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20  <td>.**         
28c90 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d   Open file "/hom
28ca0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e  e/fred/data.db".
28cb0 20 55 73 65 20 74 68 65 20 73 70 65 63 69 61 6c   Use the special
28cc0 20 56 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 69   VFS "unix-dotfi
28cd0 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  le".**          
28ce0 74 68 61 74 20 75 73 65 73 20 64 6f 74 2d 66 69  that uses dot-fi
28cf0 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  les in place of 
28d00 70 6f 73 69 78 20 61 64 76 69 73 6f 72 79 20 6c  posix advisory l
28d10 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c  ocking..** <tr><
28d20 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
28d30 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c  ?mode=readonly <
28d40 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
28d50 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64   An error. "read
28d60 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76  only" is not a v
28d70 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20  alid option for 
28d80 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d  the "mode" param
28d90 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65  eter..** </table
28da0 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78  >.**.** ^URI hex
28db0 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
28dc0 73 65 71 75 65 6e 63 65 73 20 28 25 48 48 29 20  sequences (%HH) 
28dd0 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 77 69  are supported wi
28de0 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e  thin the path an
28df0 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f  d.** query compo
28e00 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20  nents of a URI. 
28e10 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  A hexadecimal es
28e20 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f  cape sequence co
28e30 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70  nsists of a.** p
28e40 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25  ercent sign - "%
28e50 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  " - followed by 
28e60 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61  exactly two hexa
28e70 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a  decimal digits .
28e80 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e  ** specifying an
28e90 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42   octet value. ^B
28ea0 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f  efore the path o
28eb0 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  r query componen
28ec0 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66  ts of a.** URI f
28ed0 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65  ilename are inte
28ee0 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 61 72  rpreted, they ar
28ef0 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20  e encoded using 
28f00 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a  UTF-8 and all .*
28f10 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  * hexadecimal es
28f20 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 72  cape sequences r
28f30 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e  eplaced by a sin
28f40 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e  gle byte contain
28f50 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65  ing the.** corre
28f60 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20  sponding octet. 
28f70 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  If this process 
28f80 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76  generates an inv
28f90 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64  alid UTF-8 encod
28fa0 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75  ing,.** the resu
28fb0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
28fc0 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65  d..**.** <b>Note
28fd0 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72   to Windows user
28fe0 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f  s:</b>  The enco
28ff0 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68  ding used for th
29000 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
29010 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  ent.** of sqlite
29020 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
29030 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d  ite3_open_v2() m
29040 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f  ust be UTF-8, no
29050 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f  t whatever.** co
29060 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e  depage is curren
29070 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69  tly defined.  Fi
29080 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69  lenames containi
29090 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c  ng international
290a0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d  .** characters m
290b0 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
290c0 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20   to UTF-8 prior 
290d0 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20  to passing them 
290e0 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  into.** sqlite3_
290f0 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
29100 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
29110 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
29120 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73  ndows Runtime us
29130 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65  ers:</b>  The te
29140 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72  mporary director
29150 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a  y must be set.**
29160 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
29170 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  g sqlite3_open()
29180 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
29190 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73  _v2().  Otherwis
291a0 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65  e, various.** fe
291b0 61 74 75 72 65 73 20 74 68 61 74 20 72 65 71 75  atures that requ
291c0 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 74  ire the use of t
291d0 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d  emporary files m
291e0 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53  ay fail..**.** S
291f0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
29200 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79  3_temp_directory
29210 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ].*/.SQLITE_API 
29220 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
29230 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  LL sqlite3_open(
29240 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
29250 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
29260 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
29270 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
29280 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
29290 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
292a0 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
292b0 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
292c0 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
292d0 4c 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  L sqlite3_open16
292e0 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  (.  const void *
292f0 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
29300 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
29310 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73   (UTF-16) */.  s
29320 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
29330 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
29340 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
29350 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
29360 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
29370 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ALL sqlite3_open
29380 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  _v2(.  const cha
29390 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
293a0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
293b0 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
293c0 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c   sqlite3 **ppDb,
293d0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
293e0 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
293f0 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73  e */.  int flags
29400 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
29410 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e  * Flags */.  con
29420 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20  st char *zVfs   
29430 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
29440 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73  VFS module to us
29450 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
29460 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20  API3REF: Obtain 
29470 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50  Values For URI P
29480 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20  arameters.**.** 
29490 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74  These are utilit
294a0 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66  y routines, usef
294b0 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d  ul to VFS implem
294c0 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20  entations, that 
294d0 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20  check.** to see 
294e0 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69  if a database fi
294f0 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61  le was a URI tha
29500 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70  t contained a sp
29510 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a  ecific query .**
29520 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20   parameter, and 
29530 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68  if so obtains th
29540 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  e value of that 
29550 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e  query parameter.
29560 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74  .**.** If F is t
29570 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
29580 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73  name pointer pas
29590 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
295a0 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a  en() method of .
295b0 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65  ** a VFS impleme
295c0 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65  ntation when the
295d0 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
295e0 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20   to xOpen() has 
295f0 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20  one or .** more 
29600 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  of the [SQLITE_O
29610 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c  PEN_URI] or [SQL
29620 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
29630 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a  ] bits set and.*
29640 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20  * P is the name 
29650 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72  of the query par
29660 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  ameter, then.** 
29670 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
29680 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
29690 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ns the value of 
296a0 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74  the P.** paramet
296b0 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20  er if it exists 
296c0 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  or a NULL pointe
296d0 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20  r if P does not 
296e0 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20  appear as a .** 
296f0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
29700 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61  on F.  If P is a
29710 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
29720 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20   of F.** has no 
29730 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20  explicit value, 
29740 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
29750 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
29760 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69  returns.** a poi
29770 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79  nter to an empty
29780 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54   string..**.** T
29790 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
297a0 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
297b0 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68  utine assumes th
297c0 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61  at P is a boolea
297d0 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61  n.** parameter a
297e0 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  nd returns true 
297f0 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29  (1) or false (0)
29800 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68   according to th
29810 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e  e value.** of P.
29820 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72    The sqlite3_ur
29830 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
29840 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
29850 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68 65   true (1) if the
29860 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65  .** value of que
29870 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
29880 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20  s one of "yes", 
29890 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20  "true", or "on" 
298a0 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f  in any.** case o
298b0 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62  r if the value b
298c0 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e  egins with a non
298d0 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54  -zero number.  T
298e0 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  he .** sqlite3_u
298f0 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
29900 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  ) routines retur
29910 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 20  ns false (0) if 
29920 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  the value of.** 
29930 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
29940 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22  P is one of "no"
29950 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f  , "false", or "o
29960 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20  ff" in any case 
29970 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c  or.** if the val
29980 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  ue begins with a
29990 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20   numeric zero.  
299a0 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75  If P is not a qu
299b0 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
299c0 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20   on F or if the 
299d0 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f  value of P is do
299e0 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79  es not match any
299f0 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65   of the.** above
29a00 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
29a10 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
29a20 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29  ) returns (B!=0)
29a30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
29a40 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c  te3_uri_int64(F,
29a50 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e  P,D) routine con
29a60 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20  verts the value 
29a70 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36  of P into a.** 6
29a80 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
29a90 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eger and returns
29aa0 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f   that integer, o
29ab0 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f  r D if P does no
29ac0 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20  t.** exist.  If 
29ad0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
29ae0 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65  s something othe
29af0 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65  r than an intege
29b00 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20  r, then.** zero 
29b10 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
29b20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55  .** If F is a NU
29b30 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
29b40 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
29b50 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
29b60 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20  rns NULL and.** 
29b70 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
29b80 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72  ean(F,P,B) retur
29b90 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e  ns B.  If F is n
29ba0 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ot a NULL pointe
29bb0 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20  r and.** is not 
29bc0 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
29bd0 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72  pathname pointer
29be0 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 73   that SQLite pas
29bf0 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
29c00 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64  en.** VFS method
29c10 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
29c20 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ior of this rout
29c30 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ine is undefined
29c40 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a   and probably.**
29c50 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f   undesirable..*/
29c60 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
29c70 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53  t char *SQLITE_S
29c80 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 75  TDCALL sqlite3_u
29c90 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e  ri_parameter(con
29ca0 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
29cb0 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  me, const char *
29cc0 7a 50 61 72 61 6d 29 3b 0a 53 51 4c 49 54 45 5f  zParam);.SQLITE_
29cd0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
29ce0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 75  TDCALL sqlite3_u
29cf0 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74  ri_boolean(const
29d00 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f   char *zFile, co
29d10 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d  nst char *zParam
29d20 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b  , int bDefault);
29d30 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
29d40 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 45  te3_int64 SQLITE
29d50 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
29d60 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74  _uri_int64(const
29d70 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68   char*, const ch
29d80 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  ar*, sqlite3_int
29d90 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  64);.../*.** CAP
29da0 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64  I3REF: Error Cod
29db0 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a  es And Messages.
29dc0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
29dd0 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  e3.**.** ^If the
29de0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 71 6c   most recent sql
29df0 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20  ite3_* API call 
29e00 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
29e10 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
29e20 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61 69 6c  nnection] D fail
29e30 65 64 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ed, then the sql
29e40 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29 20  ite3_errcode(D) 
29e50 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74  interface.** ret
29e60 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63  urns the numeric
29e70 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f   [result code] o
29e80 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  r [extended resu
29e90 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 61  lt code] for tha
29ea0 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e 0a 2a  t.** API call..*
29eb0 2a 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65  * If the most re
29ec0 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 77 61  cent API call wa
29ed0 73 20 73 75 63 63 65 73 73 66 75 6c 2c 0a 2a 2a  s successful,.**
29ee0 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
29ef0 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
29f00 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73  te3_errcode() is
29f10 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e   undefined..** ^
29f20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
29f30 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a  nded_errcode().*
29f40 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
29f50 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74  he same except t
29f60 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65  hat it always re
29f70 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65  turns the .** [e
29f80 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
29f90 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65  ode] even when e
29fa0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
29fb0 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61  odes are.** disa
29fc0 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
29fd0 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
29fe0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72  ) and sqlite3_er
29ff0 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20  rmsg16() return 
2a000 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
2a010 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65  .** text that de
2a020 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
2a030 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46  r, as either UTF
2a040 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73  -8 or UTF-16 res
2a050 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28  pectively..** ^(
2a060 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
2a070 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
2a080 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
2a090 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a  ed internally..*
2a0a0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
2a0b0 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  n does not need 
2a0c0 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66  to worry about f
2a0d0 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c  reeing the resul
2a0e0 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  t..** However, t
2a0f0 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20  he error string 
2a100 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69  might be overwri
2a110 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tten or dealloca
2a120 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71  ted by.** subseq
2a130 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74  uent calls to ot
2a140 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
2a150 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29  face functions.)
2a160 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
2a170 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e  ite3_errstr() in
2a180 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2a190 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  the English-lang
2a1a0 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61  uage text.** tha
2a1b0 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
2a1c0 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61  [result code], a
2a1d0 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65  s UTF-8..** ^(Me
2a1e0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
2a1f0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
2a200 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
2a210 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61   internally.** a
2a220 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66  nd must not be f
2a230 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  reed by the appl
2a240 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a  ication)^..**.**
2a250 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c   When the serial
2a260 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
2a270 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c  mode] is in use,
2a280 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65   it might be the
2a290 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20  .** case that a 
2a2a0 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63  second error occ
2a2b0 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74  urs on a separat
2a2c0 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77  e thread in betw
2a2d0 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20  een.** the time 
2a2e0 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72  of the first err
2a2f0 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20  or and the call 
2a300 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
2a310 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61  ces..** When tha
2a320 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73  t happens, the s
2a330 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c  econd error will
2a340 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e   be reported sin
2a350 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65  ce these.** inte
2a360 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65  rfaces always re
2a370 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65  port the most re
2a380 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f  cent result.  To
2a390 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20   avoid.** this, 
2a3a0 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20  each thread can 
2a3b0 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65  obtain exclusive
2a3c0 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74   use of the [dat
2a3d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2a3e0 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69  ] D.** by invoki
2a3f0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
2a400 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65  x_enter]([sqlite
2a410 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
2a420 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67  before beginning
2a430 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64  .** to use D and
2a440 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
2a450 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28  e3_mutex_leave](
2a460 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
2a470 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20  x](D)) after.** 
2a480 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  all calls to the
2a490 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74   interfaces list
2a4a0 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70  ed here are comp
2a4b0 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  leted..**.** If 
2a4c0 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69  an interface fai
2a4d0 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d  ls with SQLITE_M
2a4e0 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e  ISUSE, that mean
2a4f0 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a  s the interface.
2a500 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69  ** was invoked i
2a510 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68  ncorrectly by th
2a520 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
2a530 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68  In that case, th
2a540 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20  e.** error code 
2a550 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20  and message may 
2a560 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65  or may not be se
2a570 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  t..*/.SQLITE_API
2a580 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
2a590 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 72 72 63  ALL sqlite3_errc
2a5a0 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
2a5b0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2a5c0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
2a5d0 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
2a5e0 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
2a5f0 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50   *db);.SQLITE_AP
2a600 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51  I const char *SQ
2a610 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2a620 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69  ite3_errmsg(sqli
2a630 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  te3*);.SQLITE_AP
2a640 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51  I const void *SQ
2a650 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2a660 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71  ite3_errmsg16(sq
2a670 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f  lite3*);.SQLITE_
2a680 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
2a690 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2a6a0 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e  qlite3_errstr(in
2a6b0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2a6c0 52 45 46 3a 20 50 72 65 70 61 72 65 64 20 53 74  REF: Prepared St
2a6d0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
2a6e0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65  * KEYWORDS: {pre
2a6f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d  pared statement}
2a700 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
2a710 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ments}.**.** An 
2a720 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
2a730 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
2a740 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  ts a single SQL 
2a750 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a  statement that.*
2a760 2a 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 69  * has been compi
2a770 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61 72 79 20  led into binary 
2a780 66 6f 72 6d 20 61 6e 64 20 69 73 20 72 65 61 64  form and is read
2a790 79 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65  y to be evaluate
2a7a0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f  d..**.** Think o
2a7b0 66 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  f each SQL state
2a7c0 6d 65 6e 74 20 61 73 20 61 20 73 65 70 61 72 61  ment as a separa
2a7d0 74 65 20 63 6f 6d 70 75 74 65 72 20 70 72 6f 67  te computer prog
2a7e0 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69  ram.  The.** ori
2a7f0 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 20 69  ginal SQL text i
2a800 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20  s source code.  
2a810 41 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  A prepared state
2a820 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20  ment object .** 
2a830 69 73 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20  is the compiled 
2a840 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20 20 41 6c  object code.  Al
2a850 6c 20 53 51 4c 20 6d 75 73 74 20 62 65 20 63 6f  l SQL must be co
2a860 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a  nverted into a.*
2a870 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
2a880 6d 65 6e 74 20 62 65 66 6f 72 65 20 69 74 20 63  ment before it c
2a890 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a  an be run..**.**
2a8a0 20 54 68 65 20 6c 69 66 65 2d 63 79 63 6c 65 20   The life-cycle 
2a8b0 6f 66 20 61 20 70 72 65 70 61 72 65 64 20 73 74  of a prepared st
2a8c0 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75  atement object u
2a8d0 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65  sually goes like
2a8e0 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   this:.**.** <ol
2a8f0 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65  >.** <li> Create
2a900 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
2a910 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75  atement object u
2a920 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
2a930 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20  epare_v2()]..** 
2a940 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73  <li> Bind values
2a950 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 73 5d   to [parameters]
2a960 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
2a970 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20  e3_bind_*().**  
2a980 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a      interfaces..
2a990 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20  ** <li> Run the 
2a9a0 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  SQL by calling [
2a9b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2a9c0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
2a9d0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74  s..** <li> Reset
2a9e0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
2a9f0 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
2aa00 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2aa10 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20  then go back.** 
2aa20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20       to step 2. 
2aa30 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72   Do this zero or
2aa40 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
2aa50 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65  <li> Destroy the
2aa60 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
2aa70 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2aa80 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a  )]..** </ol>.*/.
2aa90 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
2aaa0 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
2aab0 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
2aac0 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74   CAPI3REF: Run-t
2aad0 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45  ime Limits.** ME
2aae0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
2aaf0 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72  .** ^(This inter
2ab00 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20  face allows the 
2ab10 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20  size of various 
2ab20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
2ab30 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61   limited.** on a
2ab40 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63   connection by c
2ab50 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e  onnection basis.
2ab60 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61    The first para
2ab70 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
2ab80 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2ab90 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69  tion] whose limi
2aba0 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f  t is to be set o
2abb0 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a  r queried.  The.
2abc0 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
2abd0 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ter is one of th
2abe0 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  e [limit categor
2abf0 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65  ies] that define
2ac00 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63   a.** class of c
2ac10 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
2ac20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54  size limited.  T
2ac30 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
2ac40 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77  er is the.** new
2ac50 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20   limit for that 
2ac60 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a  construct.)^.**.
2ac70 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c  ** ^If the new l
2ac80 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69  imit is a negati
2ac90 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c  ve number, the l
2aca0 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65  imit is unchange
2acb0 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68  d..** ^(For each
2acc0 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20   limit category 
2acd0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e  SQLITE_LIMIT_<i>
2ace0 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69  NAME</i> there i
2acf0 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  s a .** [limits 
2ad00 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  | hard upper bou
2ad10 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f  nd].** set at co
2ad20 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20  mpile-time by a 
2ad30 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
2ad40 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b  acro called.** [
2ad50 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f  limits | SQLITE_
2ad60 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d  MAX_<i>NAME</i>]
2ad70 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49  ..** (The "_LIMI
2ad80 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  T_" in the name 
2ad90 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f  is changed to "_
2ada0 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74  MAX_".))^.** ^At
2adb0 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61  tempts to increa
2adc0 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65  se a limit above
2add0 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20   its hard upper 
2ade0 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c  bound are.** sil
2adf0 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20  ently truncated 
2ae00 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65  to the hard uppe
2ae10 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e  r bound..**.** ^
2ae20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  Regardless of wh
2ae30 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
2ae40 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67   limit was chang
2ae50 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c  ed, the .** [sql
2ae60 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e  ite3_limit()] in
2ae70 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2ae80 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20  the prior value 
2ae90 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a  of the limit..**
2aea0 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64   ^Hence, to find
2aeb0 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
2aec0 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69  ue of a limit wi
2aed0 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69  thout changing i
2aee0 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76  t,.** simply inv
2aef0 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61  oke this interfa
2af00 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72  ce with the thir
2af10 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20  d parameter set 
2af20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e  to -1..**.** Run
2af30 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65  -time limits are
2af40 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
2af50 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  e in application
2af60 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a  s that manage.**
2af70 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20   both their own 
2af80 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
2af90 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62  e and also datab
2afa0 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f  ases that are co
2afb0 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75  ntrolled.** by u
2afc0 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61  ntrusted externa
2afd0 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65  l sources.  An e
2afe0 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69  xample applicati
2aff0 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a  on might be a.**
2b000 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61   web browser tha
2b010 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61  t has its own da
2b020 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72  tabases for stor
2b030 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a  ing history and.
2b040 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61  ** separate data
2b050 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64  bases controlled
2b060 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61   by JavaScript a
2b070 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e  pplications down
2b080 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68  loaded.** off th
2b090 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65  e Internet.  The
2b0a0 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
2b0b0 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e  ses can be given
2b0c0 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64   the.** large, d
2b0d0 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20  efault limits.  
2b0e0 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65  Databases manage
2b0f0 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f  d by external so
2b100 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20  urces can.** be 
2b110 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c  given much small
2b120 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e  er limits design
2b130 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ed to prevent a 
2b140 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63  denial of servic
2b150 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65  e.** attack.  De
2b160 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61  velopers might a
2b170 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20  lso want to use 
2b180 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  the [sqlite3_set
2b190 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a  _authorizer()].*
2b1a0 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66  * interface to f
2b1b0 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75  urther control u
2b1c0 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54  ntrusted SQL.  T
2b1d0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64  he size of the d
2b1e0 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74  atabase.** creat
2b1f0 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74  ed by an untrust
2b200 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65  ed script can be
2b210 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67   contained using
2b220 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67   the.** [max_pag
2b230 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
2b240 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e  ]..**.** New run
2b250 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65  -time limit cate
2b260 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64  gories may be ad
2b270 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
2b280 6c 65 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54  leases..*/.SQLIT
2b290 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
2b2a0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2b2b0 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c  _limit(sqlite3*,
2b2c0 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77   int id, int new
2b2d0 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Val);../*.** CAP
2b2e0 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
2b2f0 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73  Limit Categories
2b300 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c  .** KEYWORDS: {l
2b310 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b  imit category} {
2b320 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  *limit categorie
2b330 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  s}.**.** These c
2b340 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
2b350 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61  various performa
2b360 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68  nce limits.** th
2b370 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65  at can be lowere
2b380 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73  d at run-time us
2b390 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
2b3a0 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79  it()]..** The sy
2b3b0 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65  nopsis of the me
2b3c0 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61  anings of the va
2b3d0 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20  rious limits is 
2b3e0 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20  shown below..** 
2b3f0 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  Additional infor
2b400 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61  mation is availa
2b410 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c  ble at [limits |
2b420 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74   Limits in SQLit
2b430 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  e]..**.** <dl>.*
2b440 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
2b450 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e  _LENGTH]] ^(<dt>
2b460 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
2b470 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
2b480 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  The maximum size
2b490 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f   of any string o
2b4a0 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20  r BLOB or table 
2b4b0 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64  row, in bytes.<d
2b4c0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
2b4d0 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
2b4e0 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  NGTH]] ^(<dt>SQL
2b4f0 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
2b500 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
2b510 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
2b520 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74  gth of an SQL st
2b530 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65  atement, in byte
2b540 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
2b550 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  [[SQLITE_LIMIT_C
2b560 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51  OLUMN]] ^(<dt>SQ
2b570 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
2b580 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  N</dt>.** <dd>Th
2b590 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
2b5a0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
2b5b0 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f   table definitio
2b5c0 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72  n or in the.** r
2b5d0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b  esult set of a [
2b5e0 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d  SELECT] or the m
2b5f0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
2b600 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69   columns in an i
2b610 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e  ndex.** or in an
2b620 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f   ORDER BY or GRO
2b630 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64  UP BY clause.</d
2b640 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
2b650 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
2b660 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  EPTH]] ^(<dt>SQL
2b670 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
2b680 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
2b690 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
2b6a0 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20  th of the parse 
2b6b0 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72  tree on any expr
2b6c0 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a  ession.</dd>)^.*
2b6d0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
2b6e0 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
2b6f0 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ECT]] ^(<dt>SQLI
2b700 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
2b710 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a  D_SELECT</dt>.**
2b720 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
2b730 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73   number of terms
2b740 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53   in a compound S
2b750 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e  ELECT statement.
2b760 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
2b770 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
2b780 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  E_OP]] ^(<dt>SQL
2b790 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
2b7a0 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  P</dt>.** <dd>Th
2b7b0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
2b7c0 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73   of instructions
2b7d0 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61   in a virtual ma
2b7e0 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a  chine program.**
2b7f0 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
2b800 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  nt an SQL statem
2b810 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74  ent.  This limit
2b820 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
2b830 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74  y.** enforced, t
2b840 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 74  hough that might
2b850 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d   be added in som
2b860 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  e future release
2b870 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f   of.** SQLite.</
2b880 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
2b890 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
2b8a0 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e  ION_ARG]] ^(<dt>
2b8b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
2b8c0 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a  CTION_ARG</dt>.*
2b8d0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
2b8e0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  m number of argu
2b8f0 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74  ments on a funct
2b900 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ion.</dd>)^.**.*
2b910 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
2b920 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64  _ATTACHED]] ^(<d
2b930 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  t>SQLITE_LIMIT_A
2b940 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20  TTACHED</dt>.** 
2b950 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
2b960 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43  number of [ATTAC
2b970 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74  H | attached dat
2b980 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a  abases].)^</dd>.
2b990 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
2b9a0 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
2b9b0 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28  N_LENGTH]].** ^(
2b9c0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
2b9d0 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
2b9e0 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
2b9f0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
2ba00 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65  gth of the patte
2ba10 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rn argument to t
2ba20 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20  he [LIKE] or.** 
2ba30 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73  [GLOB] operators
2ba40 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
2ba50 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
2ba60 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a  RIABLE_NUMBER]].
2ba70 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
2ba80 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
2ba90 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  UMBER</dt>.** <d
2baa0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e  d>The maximum in
2bab0 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e  dex number of an
2bac0 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  y [parameter] in
2bad0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
2bae0 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  t.)^.**.** [[SQL
2baf0 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
2bb00 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e  R_DEPTH]] ^(<dt>
2bb10 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
2bb20 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  GGER_DEPTH</dt>.
2bb30 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
2bb40 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75  um depth of recu
2bb50 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65  rsion for trigge
2bb60 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  rs.</dd>)^.**.**
2bb70 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
2bb80 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d  WORKER_THREADS]]
2bb90 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
2bba0 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41  MIT_WORKER_THREA
2bbb0 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  DS</dt>.** <dd>T
2bbc0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
2bbd0 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79 20 77  r of auxiliary w
2bbe0 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20 74 68  orker threads th
2bbf0 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b  at a single.** [
2bc00 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2bc10 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f  nt] may start.</
2bc20 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
2bc30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2bc40 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20  _LIMIT_LENGTH   
2bc50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2bc60 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
2bc70 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
2bc80 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
2bc90 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
2bca0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20  TE_LIMIT_COLUMN 
2bcb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2bcc0 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
2bcd0 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
2bce0 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
2bcf0 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
2bd00 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
2bd10 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20  UND_SELECT      
2bd20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
2bd30 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
2bd40 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20  _OP             
2bd50 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
2bd60 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
2bd70 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20  CTION_ARG       
2bd80 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
2bd90 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54   SQLITE_LIMIT_AT
2bda0 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20  TACHED          
2bdb0 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
2bdc0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
2bdd0 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
2bde0 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69  TH       8.#defi
2bdf0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2be00 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20  VARIABLE_NUMBER 
2be10 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66            9.#def
2be20 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2be30 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20  _TRIGGER_DEPTH  
2be40 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65            10.#de
2be50 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2be60 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53  T_WORKER_THREADS
2be70 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a 2f             11../
2be80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
2be90 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20  ompiling An SQL 
2bea0 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59  Statement.** KEY
2beb0 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74  WORDS: {SQL stat
2bec0 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a  ement compiler}.
2bed0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2bee0 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f  e3.** CONSTRUCTO
2bef0 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  R: sqlite3_stmt.
2bf00 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65  **.** To execute
2bf10 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69   an SQL query, i
2bf20 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20  t must first be 
2bf30 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20  compiled into a 
2bf40 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f  byte-code.** pro
2bf50 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f  gram using one o
2bf60 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
2bf70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
2bf80 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22  t argument, "db"
2bf90 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65  , is a [database
2bfa0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74   connection] obt
2bfb0 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  ained from a.** 
2bfc0 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c  prior successful
2bfd0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2bfe0 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
2bff0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f  te3_open_v2()] o
2c000 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r.** [sqlite3_op
2c010 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61  en16()].  The da
2c020 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2c030 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20  n must not have 
2c040 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  been closed..**.
2c050 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
2c060 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20  gument, "zSql", 
2c070 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  is the statement
2c080 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c   to be compiled,
2c090 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65   encoded.** as e
2c0a0 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55  ither UTF-8 or U
2c0b0 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69  TF-16.  The sqli
2c0c0 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e  te3_prepare() an
2c0d0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
2c0e0 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66  e_v2().** interf
2c0f0 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20  aces use UTF-8, 
2c100 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
2c110 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69  are16() and sqli
2c120 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2c130 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36  ().** use UTF-16
2c140 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2c150 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69  nByte argument i
2c160 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
2c170 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70   zSql is read up
2c180 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   to the.** first
2c190 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
2c1a0 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 70  . ^If nByte is p
2c1b0 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 69 74  ositive, then it
2c1c0 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
2c1d0 72 20 6f 66 20 62 79 74 65 73 20 72 65 61 64 20  r of bytes read 
2c1e0 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66 20  from zSql.  ^If 
2c1f0 6e 42 79 74 65 20 69 73 20 7a 65 72 6f 2c 20 74  nByte is zero, t
2c200 68 65 6e 20 6e 6f 20 70 72 65 70 61 72 65 64 0a  hen no prepared.
2c210 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ** statement is 
2c220 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49 66  generated..** If
2c230 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77   the caller know
2c240 73 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c  s that the suppl
2c250 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75  ied string is nu
2c260 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68  l-terminated, th
2c270 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73 20 61  en.** there is a
2c280 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61 6e   small performan
2c290 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20  ce advantage to 
2c2a0 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65  passing an nByte
2c2b0 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a   parameter that.
2c2c0 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ** is the number
2c2d0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
2c2e0 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69   input string <i
2c2f0 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a  >including</i>.*
2c300 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e  * the nul-termin
2c310 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ator..**.** ^If 
2c320 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55  pzTail is not NU
2c330 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20  LL then *pzTail 
2c340 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
2c350 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79   to the first by
2c360 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65  te.** past the e
2c370 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  nd of the first 
2c380 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
2c390 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f   zSql.  These ro
2c3a0 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63  utines only.** c
2c3b0 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74  ompile the first
2c3c0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
2c3d0 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69  ql, so *pzTail i
2c3e0 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
2c3f0 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69  to.** what remai
2c400 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a  ns uncompiled..*
2c410 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73  *.** ^*ppStmt is
2c420 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
2c430 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72  o a compiled [pr
2c440 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c450 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a  ] that can be.**
2c460 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20   executed using 
2c470 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2c480 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20  .  ^If there is 
2c490 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d  an error, *ppStm
2c4a0 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e  t is set.** to N
2c4b0 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e  ULL.  ^If the in
2c4c0 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
2c4d0 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65  s no SQL (if the
2c4e0 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70   input is an emp
2c4f0 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20  ty.** string or 
2c500 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20  a comment) then 
2c510 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74  *ppStmt is set t
2c520 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63  o NULL..** The c
2c530 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65  alling procedure
2c540 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
2c550 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65  for deleting the
2c560 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c   compiled.** SQL
2c570 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
2c580 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2c590 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68  ze()] after it h
2c5a0 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
2c5b0 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d   it..** ppStmt m
2c5c0 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a  ay not be NULL..
2c5d0 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73  **.** ^On succes
2c5e0 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70  s, the sqlite3_p
2c5f0 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20  repare() family 
2c600 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  of routines retu
2c610 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a  rn [SQLITE_OK];.
2c620 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  ** otherwise an 
2c630 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
2c640 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
2c650 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
2c660 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c  are_v2() and sql
2c670 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2c680 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61  2() interfaces a
2c690 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65  re.** recommende
2c6a0 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72  d for all new pr
2c6b0 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20  ograms. The two 
2c6c0 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73  older interfaces
2c6d0 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a   are retained.**
2c6e0 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
2c6f0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75  ompatibility, bu
2c700 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64  t their use is d
2c710 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e  iscouraged..** ^
2c720 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
2c730 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70  rfaces, the prep
2c740 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
2c750 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e  * that is return
2c760 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
2c770 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63  _stmt] object) c
2c780 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f  ontains a copy o
2c790 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61  f the.** origina
2c7a0 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73  l SQL text. This
2c7b0 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c   causes the [sql
2c7c0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74  ite3_step()] int
2c7d0 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68  erface to.** beh
2c7e0 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20  ave differently 
2c7f0 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a  in three ways:.*
2c800 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
2c810 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74  >.** ^If the dat
2c820 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
2c830 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66  nges, instead of
2c840 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
2c850 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74  TE_SCHEMA] as it
2c860 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20  .** always used 
2c870 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f  to do, [sqlite3_
2c880 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74  step()] will aut
2c890 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
2c8a0 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20  pile the SQL.** 
2c8b0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72  statement and tr
2c8c0 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69  y to run it agai
2c8d0 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53  n. As many as [S
2c8e0 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41  QLITE_MAX_SCHEMA
2c8f0 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69  _RETRY].** retri
2c900 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65  es will occur be
2c910 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65  fore sqlite3_ste
2c920 70 28 29 20 67 69 76 65 73 20 75 70 20 61 6e 64  p() gives up and
2c930 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f   returns an erro
2c940 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  r..** </li>.**.*
2c950 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20  * <li>.** ^When 
2c960 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c  an error occurs,
2c970 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2c980 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e  ] will return on
2c990 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65  e of the detaile
2c9a0 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  d.** [error code
2c9b0 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  s] or [extended 
2c9c0 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e  error codes].  ^
2c9d0 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  The legacy behav
2c9e0 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20  ior was that.** 
2c9f0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2ca00 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75   would only retu
2ca10 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51  rn a generic [SQ
2ca20 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75  LITE_ERROR] resu
2ca30 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74  lt code.** and t
2ca40 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77  he application w
2ca50 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b  ould have to mak
2ca60 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20  e a second call 
2ca70 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
2ca80 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  t()].** in order
2ca90 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64   to find the und
2caa0 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66  erlying cause of
2cab0 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69   the problem. Wi
2cac0 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70  th the "v2" prep
2cad0 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  are.** interface
2cae0 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  s, the underlyin
2caf0 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65  g reason for the
2cb00 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
2cb10 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ed immediately..
2cb20 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
2cb30 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  li>.** ^If the s
2cb40 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f  pecific value bo
2cb50 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65  und to [paramete
2cb60 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  r | host paramet
2cb70 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57  er] in the .** W
2cb80 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68  HERE clause migh
2cb90 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20  t influence the 
2cba0 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20  choice of query 
2cbb0 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65  plan for a state
2cbc0 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ment,.** then th
2cbd0 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c  e statement will
2cbe0 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
2cbf0 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73  y recompiled, as
2cc00 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65   if there had be
2cc10 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20  en .** a schema 
2cc20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66  change, on the f
2cc30 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73  irst  [sqlite3_s
2cc40 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c  tep()] call foll
2cc50 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65  owing any change
2cc60 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
2cc70 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20  te3_bind_text | 
2cc80 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61  bindings] of tha
2cc90 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a  t [parameter]. .
2cca0 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63  ** ^The specific
2ccb0 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d   value of WHERE-
2ccc0 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65  clause [paramete
2ccd0 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  r] might influen
2cce0 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63  ce the .** choic
2ccf0 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
2cd00 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
2cd10 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e   is the left-han
2cd20 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b  d side of a [LIK
2cd30 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20  E].** or [GLOB] 
2cd40 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74  operator or if t
2cd50 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
2cd60 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69  compared to an i
2cd70 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a  ndexed column.**
2cd80 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45   and the [SQLITE
2cd90 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63  _ENABLE_STAT3] c
2cda0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
2cdb0 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  on is enabled..*
2cdc0 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e  * </li>.** </ol>
2cdd0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
2cde0 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
2cdf0 4c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  L sqlite3_prepar
2ce00 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
2ce10 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
2ce20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
2ce30 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2ce40 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
2ce50 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
2ce60 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
2ce70 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
2ce80 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
2ce90 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
2cea0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
2ceb0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
2cec0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
2ced0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
2cee0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
2cef0 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
2cf00 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
2cf10 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
2cf20 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
2cf30 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2cf40 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2cf50 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2cf60 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
2cf70 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
2cf80 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
2cf90 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2cfa0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
2cfb0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
2cfc0 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
2cfd0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
2cfe0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
2cff0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
2d000 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
2d010 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
2d020 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
2d030 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
2d040 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
2d050 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
2d060 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
2d070 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
2d080 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
2d090 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2d0a0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2d0b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2d0c0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2d0d0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
2d0e0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
2d0f0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
2d100 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
2d110 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
2d120 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
2d130 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
2d140 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
2d150 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
2d160 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
2d170 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
2d180 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
2d190 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
2d1a0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
2d1b0 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
2d1c0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
2d1d0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
2d1e0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
2d1f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2d200 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2d210 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2d220 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
2d230 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
2d240 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
2d250 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
2d260 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
2d270 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
2d280 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
2d290 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
2d2a0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2d2b0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
2d2c0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
2d2d0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
2d2e0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
2d2f0 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
2d300 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2d310 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
2d320 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
2d330 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
2d340 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
2d350 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
2d360 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20  REF: Retrieving 
2d370 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a  Statement SQL.**
2d380 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2d390 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
2d3a0 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 50 29 20   sqlite3_sql(P) 
2d3b0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2d3c0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
2d3d0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 55 54 46   copy of the UTF
2d3e0 2d 38 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75  -8.** SQL text u
2d3f0 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 5b 70  sed to create [p
2d400 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d410 74 5d 20 50 20 69 66 20 50 20 77 61 73 0a 2a 2a  t] P if P was.**
2d420 20 63 72 65 61 74 65 64 20 62 79 20 65 69 74 68   created by eith
2d430 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
2d440 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
2d450 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2d460 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73  v2()]..** ^The s
2d470 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
2d480 73 71 6c 28 50 29 20 69 6e 74 65 72 66 61 63 65  sql(P) interface
2d490 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2d4a0 65 72 20 74 6f 20 61 20 55 54 46 2d 38 0a 2a 2a  er to a UTF-8.**
2d4b0 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69   string containi
2d4c0 6e 67 20 74 68 65 20 53 51 4c 20 74 65 78 74 20  ng the SQL text 
2d4d0 6f 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74  of prepared stat
2d4e0 65 6d 65 6e 74 20 50 20 77 69 74 68 0a 2a 2a 20  ement P with.** 
2d4f0 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  [bound parameter
2d500 73 5d 20 65 78 70 61 6e 64 65 64 2e 0a 2a 2a 0a  s] expanded..**.
2d510 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
2d520 2c 20 69 66 20 61 20 70 72 65 70 61 72 65 64 20  , if a prepared 
2d530 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 72 65  statement is cre
2d540 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 20 53  ated using the S
2d550 51 4c 0a 2a 2a 20 74 65 78 74 20 22 53 45 4c 45  QL.** text "SELE
2d560 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 20 61 6e  CT $abc,:xyz" an
2d570 64 20 69 66 20 70 61 72 61 6d 65 74 65 72 20 24  d if parameter $
2d580 61 62 63 20 69 73 20 62 6f 75 6e 64 20 74 6f 20  abc is bound to 
2d590 69 6e 74 65 67 65 72 20 32 33 34 35 0a 2a 2a 20  integer 2345.** 
2d5a0 61 6e 64 20 70 61 72 61 6d 65 74 65 72 20 3a 78  and parameter :x
2d5b0 79 7a 20 69 73 20 75 6e 62 6f 75 6e 64 2c 20 74  yz is unbound, t
2d5c0 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 71 6c 28  hen sqlite3_sql(
2d5d0 29 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  ) will return.**
2d5e0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
2d5f0 72 69 6e 67 2c 20 22 53 45 4c 45 43 54 20 24 61  ring, "SELECT $a
2d600 62 63 2c 3a 78 79 7a 22 20 62 75 74 20 73 71 6c  bc,:xyz" but sql
2d610 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71  ite3_expanded_sq
2d620 6c 28 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75  l().** will retu
2d630 72 6e 20 22 53 45 4c 45 43 54 20 32 33 34 35 2c  rn "SELECT 2345,
2d640 4e 55 4c 4c 22 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  NULL".)^.**.** ^
2d650 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 70 61  The sqlite3_expa
2d660 6e 64 65 64 5f 73 71 6c 28 29 20 69 6e 74 65 72  nded_sql() inter
2d670 66 61 63 65 20 72 65 74 75 72 6e 73 20 4e 55 4c  face returns NUL
2d680 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e  L if insufficien
2d690 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69 73 20 61  t memory.** is a
2d6a0 76 61 69 6c 61 62 6c 65 20 74 6f 20 68 6f 6c 64  vailable to hold
2d6b0 20 74 68 65 20 72 65 73 75 6c 74 2c 20 6f 72 20   the result, or 
2d6c0 69 66 20 74 68 65 20 72 65 73 75 6c 74 20 77 6f  if the result wo
2d6d0 75 6c 64 20 65 78 63 65 65 64 20 74 68 65 0a 2a  uld exceed the.*
2d6e0 2a 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 74  * the maximum st
2d6f0 72 69 6e 67 20 6c 65 6e 67 74 68 20 64 65 74 65  ring length dete
2d700 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 5b 53  rmined by the [S
2d710 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
2d720 54 48 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  TH]..**.** ^The 
2d730 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49  [SQLITE_TRACE_SI
2d740 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c  ZE_LIMIT] compil
2d750 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 6c 69  e-time option li
2d760 6d 69 74 73 20 74 68 65 20 73 69 7a 65 20 6f 66  mits the size of
2d770 0a 2a 2a 20 62 6f 75 6e 64 20 70 61 72 61 6d 65  .** bound parame
2d780 74 65 72 20 65 78 70 61 6e 73 69 6f 6e 73 2e 20  ter expansions. 
2d790 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d   ^The [SQLITE_OM
2d7a0 49 54 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c  IT_TRACE] compil
2d7b0 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
2d7c0 20 63 61 75 73 65 73 20 73 71 6c 69 74 65 33 5f   causes sqlite3_
2d7d0 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 20 74  expanded_sql() t
2d7e0 6f 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  o always return 
2d7f0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
2d800 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64   string returned
2d810 20 62 79 20 73 71 6c 69 74 65 33 5f 73 71 6c 28   by sqlite3_sql(
2d820 50 29 20 69 73 20 6d 61 6e 61 67 65 64 20 62 79  P) is managed by
2d830 20 53 51 4c 69 74 65 20 61 6e 64 20 69 73 0a 2a   SQLite and is.*
2d840 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
2d850 66 72 65 65 64 20 77 68 65 6e 20 74 68 65 20 70  freed when the p
2d860 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d870 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 2e 0a  t is finalized..
2d880 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e 67 20 72  ** ^The string r
2d890 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2d8a0 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
2d8b0 50 29 2c 20 6f 6e 20 74 68 65 20 6f 74 68 65 72  P), on the other
2d8c0 20 68 61 6e 64 2c 0a 2a 2a 20 69 73 20 6f 62 74   hand,.** is obt
2d8d0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
2d8e0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e  te3_malloc()] an
2d8f0 64 20 6d 75 73 74 20 62 65 20 66 72 65 65 20 62  d must be free b
2d900 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
2d910 6e 0a 2a 2a 20 62 79 20 70 61 73 73 69 6e 67 20  n.** by passing 
2d920 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  it to [sqlite3_f
2d930 72 65 65 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  ree()]..*/.SQLIT
2d940 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
2d950 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
2d960 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c   sqlite3_sql(sql
2d970 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2d980 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68  );.SQLITE_API ch
2d990 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  ar *SQLITE_STDCA
2d9a0 4c 4c 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e  LL sqlite3_expan
2d9b0 64 65 64 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f  ded_sql(sqlite3_
2d9c0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
2d9d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2d9e0 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53  etermine If An S
2d9f0 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69  QL Statement Wri
2da00 74 65 73 20 54 68 65 20 44 61 74 61 62 61 73 65  tes The Database
2da10 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2da20 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2da30 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
2da40 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74  _readonly(X) int
2da50 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
2da60 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69  rue (non-zero) i
2da70 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66  f.** and only if
2da80 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2da90 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65  tatement] X make
2daa0 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e  s no direct chan
2dab0 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f  ges to.** the co
2dac0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74  ntent of the dat
2dad0 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a  abase file..**.*
2dae0 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70  * Note that [app
2daf0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2db00 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20   SQL functions] 
2db10 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74  or.** [virtual t
2db20 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61  ables] might cha
2db30 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
2db40 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61   indirectly as a
2db50 20 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a   side effect.  .
2db60 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
2db70 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74  , if an applicat
2db80 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75  ion defines a fu
2db90 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20  nction "eval()" 
2dba0 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b  that .** calls [
2dbb0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
2dbc0 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77   then the follow
2dbd0 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
2dbe0 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67  t would.** chang
2dbf0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
2dc00 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 65  ile through side
2dc10 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20  -effects:.**.** 
2dc20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
2dc30 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65  >.**    SELECT e
2dc40 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d  val('DELETE FROM
2dc50 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a   t1') FROM t2;.*
2dc60 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
2dc70 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20  uote>.**.** But 
2dc80 62 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c  because the [SEL
2dc90 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64  ECT] statement d
2dca0 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
2dcb0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
2dcc0 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71  .** directly, sq
2dcd0 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
2dce0 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c  nly() would stil
2dcf0 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e  l return true.)^
2dd00 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74  .**.** ^Transact
2dd10 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74  ion control stat
2dd20 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b  ements such as [
2dd30 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d  BEGIN], [COMMIT]
2dd40 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a  , [ROLLBACK],.**
2dd50 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e   [SAVEPOINT], an
2dd60 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73  d [RELEASE] caus
2dd70 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  e sqlite3_stmt_r
2dd80 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74  eadonly() to ret
2dd90 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e  urn true,.** sin
2dda0 63 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ce the statement
2ddb0 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20  s themselves do 
2ddc0 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64  not actually mod
2ddd0 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65  ify the database
2dde0 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74   but.** rather t
2ddf0 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20  hey control the 
2de00 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f  timing of when o
2de10 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20  ther statements 
2de20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64  modify the .** d
2de30 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b  atabase.  ^The [
2de40 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54  ATTACH] and [DET
2de50 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20  ACH] statements 
2de60 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71  also cause.** sq
2de70 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
2de80 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20  nly() to return 
2de90 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c  true since, whil
2dea0 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e  e those statemen
2deb0 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  ts.** change the
2dec0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
2ded0 66 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  f a database con
2dee0 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f  nection, they do
2def0 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68   not make .** ch
2df00 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e  anges to the con
2df10 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61  tent of the data
2df20 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69  base files on di
2df30 73 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  sk..*/.SQLITE_AP
2df40 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
2df50 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 74 6d  CALL sqlite3_stm
2df60 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74  t_readonly(sqlit
2df70 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2df80 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2df90 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
2dfa0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
2dfb0 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73  ent Has Been Res
2dfc0 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  et.** METHOD: sq
2dfd0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2dfe0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
2dff0 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72  mt_busy(S) inter
2e000 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75  face returns tru
2e010 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20  e (non-zero) if 
2e020 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2e030 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61   statement] S ha
2e040 73 20 62 65 65 6e 20 73 74 65 70 70 65 64 20 61  s been stepped a
2e050 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69  t least once usi
2e060 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ng .** [sqlite3_
2e070 73 74 65 70 28 53 29 5d 20 62 75 74 20 68 61 73  step(S)] but has
2e080 20 6e 65 69 74 68 65 72 20 72 75 6e 20 74 6f 20   neither run to 
2e090 63 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74 75  completion (retu
2e0a0 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rned.** [SQLITE_
2e0b0 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c 69  DONE] from [sqli
2e0c0 74 65 33 5f 73 74 65 70 28 53 29 5d 29 20 6e 6f  te3_step(S)]) no
2e0d0 72 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20  r.** been reset 
2e0e0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
2e0f0 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20  eset(S)].  ^The 
2e100 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
2e110 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y(S).** interfac
2e120 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  e returns false 
2e130 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70  if S is a NULL p
2e140 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73  ointer.  If S is
2e150 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20   not a .** NULL 
2e160 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e  pointer and is n
2e170 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ot a pointer to 
2e180 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65  a valid [prepare
2e190 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
2e1a0 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65  object, then the
2e1b0 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
2e1c0 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
2e1d0 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e  bly undesirable.
2e1e0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
2e1f0 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
2e200 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  d in combination
2e210 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
2e220 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63  tmt()].** to loc
2e230 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64  ate all prepared
2e240 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f   statements asso
2e250 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61  ciated with a da
2e260 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65  tabase .** conne
2e270 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69  ction that are i
2e280 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20  n need of being 
2e290 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e  reset.  This can
2e2a0 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72   be used,.** for
2e2b0 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61   example, in dia
2e2c0 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73  gnostic routines
2e2d0 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70   to search for p
2e2e0 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74  repared .** stat
2e2f0 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20  ements that are 
2e300 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61  holding a transa
2e310 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 53  ction open..*/.S
2e320 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
2e330 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2e340 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73  ite3_stmt_busy(s
2e350 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
2e360 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2e370 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65  Dynamically Type
2e380 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a  d Value Object.*
2e390 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f  * KEYWORDS: {pro
2e3a0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2e3b0 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74  alue} {unprotect
2e3c0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2e3d0 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  }.**.** SQLite u
2e3e0 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ses the sqlite3_
2e3f0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20  value object to 
2e400 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61  represent all va
2e410 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  lues.** that can
2e420 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20   be stored in a 
2e430 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20  database table. 
2e440 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
2e450 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f  mic typing.** fo
2e460 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20  r the values it 
2e470 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73  stores.  ^Values
2e480 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74   stored in sqlit
2e490 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
2e4a0 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67  .** can be integ
2e4b0 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ers, floating po
2e4c0 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69  int values, stri
2e4d0 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e  ngs, BLOBs, or N
2e4e0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71  ULL..**.** An sq
2e4f0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2e500 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72  ct may be either
2e510 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20   "protected" or 
2e520 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a  "unprotected"..*
2e530 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65  * Some interface
2e540 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74  s require a prot
2e550 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2e560 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65  lue.  Other inte
2e570 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61  rfaces.** will a
2e580 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70  ccept either a p
2e590 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75  rotected or an u
2e5a0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2e5b0 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65  e3_value..** Eve
2e5c0 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ry interface tha
2e5d0 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65  t accepts sqlite
2e5e0 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74  3_value argument
2e5f0 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  s specifies.** w
2e600 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74  hether or not it
2e610 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74   requires a prot
2e620 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2e630 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71  lue.  The.** [sq
2e640 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28  lite3_value_dup(
2e650 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  )] interface can
2e660 20 62 65 20 75 73 65 64 20 74 6f 20 63 6f 6e 73   be used to cons
2e670 74 72 75 63 74 20 61 20 6e 65 77 20 0a 2a 2a 20  truct a new .** 
2e680 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2e690 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e 20  3_value from an 
2e6a0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2e6b0 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  te3_value..**.**
2e6c0 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74   The terms "prot
2e6d0 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72  ected" and "unpr
2e6e0 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74  otected" refer t
2e6f0 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  o whether or not
2e700 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68  .** a mutex is h
2e710 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61  eld.  An interna
2e720 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  l mutex is held 
2e730 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a  for a protected.
2e740 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
2e750 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d   object but no m
2e760 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
2e770 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a   an unprotected.
2e780 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
2e790 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c   object.  If SQL
2e7a0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
2e7b0 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72  to be single-thr
2e7c0 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b  eaded.** (with [
2e7d0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
2e7e0 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73  E=0] and with [s
2e7f0 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
2e800 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30  e()] returning 0
2e810 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74  ).** or if SQLit
2e820 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20  e is run in one 
2e830 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78  of reduced mutex
2e840 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49   modes .** [SQLI
2e850 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2e860 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49  THREAD] or [SQLI
2e870 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
2e880 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74  HREAD].** then t
2e890 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69  here is no disti
2e8a0 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
2e8b0 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
2e8c0 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
2e8d0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2e8e0 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62  s and they can b
2e8f0 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e  e used interchan
2e900 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72  geably.  However
2e910 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d  ,.** for maximum
2e920 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74   code portabilit
2e930 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  y it is recommen
2e940 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
2e950 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d  tions.** still m
2e960 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74  ake the distinct
2e970 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  ion between prot
2e980 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
2e990 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
2e9a0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65  _value objects e
2e9b0 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72  ven when not str
2e9c0 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a  ictly required..
2e9d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2e9e0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
2e9f0 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64   that are passed
2ea00 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69   as parameters i
2ea10 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65  nto the.** imple
2ea20 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70  mentation of [ap
2ea30 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2ea40 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
2ea50 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a   are protected..
2ea60 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2ea70 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74  value object ret
2ea80 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
2ea90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2eaa0 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63  e()] is unprotec
2eab0 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63  ted..** Unprotec
2eac0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2ead0 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e  e objects may on
2eae0 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a  ly be used with.
2eaf0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ** [sqlite3_resu
2eb00 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  lt_value()] and 
2eb10 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
2eb20 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b  lue()]..** The [
2eb30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
2eb40 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c  ob | sqlite3_val
2eb50 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c  ue_type()] famil
2eb60 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y of.** interfac
2eb70 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65  es require prote
2eb80 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2eb90 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74  ue objects..*/.t
2eba0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65  ypedef struct Me
2ebb0 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b  m sqlite3_value;
2ebc0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ebd0 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43  : SQL Function C
2ebe0 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a  ontext Object.**
2ebf0 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20  .** The context 
2ec00 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20  in which an SQL 
2ec10 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65  function execute
2ec20 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61  s is stored in a
2ec30 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  n.** sqlite3_con
2ec40 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41  text object.  ^A
2ec50 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73   pointer to an s
2ec60 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
2ec70 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61  bject.** is alwa
2ec80 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  ys first paramet
2ec90 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69  er to [applicati
2eca0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2ecb0 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68  unctions]..** Th
2ecc0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
2ecd0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2ece0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
2ecf0 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73  n will pass this
2ed00 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f  .** pointer thro
2ed10 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74  ugh into calls t
2ed20 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  o [sqlite3_resul
2ed30 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f  t_int | sqlite3_
2ed40 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73  result()],.** [s
2ed50 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2ed60 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71  _context()], [sq
2ed70 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
2ed80 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
2ed90 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
2eda0 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67  e()], [sqlite3_g
2edb0 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a  et_auxdata()],.*
2edc0 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65  * and/or [sqlite
2edd0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_set_auxdata()]
2ede0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
2edf0 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  uct sqlite3_cont
2ee00 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext sqlite3_cont
2ee10 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ext;../*.** CAPI
2ee20 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61  3REF: Binding Va
2ee30 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64  lues To Prepared
2ee40 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b   Statements.** K
2ee50 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70  EYWORDS: {host p
2ee60 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20  arameter} {host 
2ee70 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73  parameters} {hos
2ee80 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
2ee90 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
2eea0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  SQL parameter} {
2eeb0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20  SQL parameters} 
2eec0 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69  {parameter bindi
2eed0 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ng}.** METHOD: s
2eee0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2eef0 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73  * ^(In the SQL s
2ef00 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e  tatement text in
2ef10 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
2ef20 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
2ef30 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a  d its variants,.
2ef40 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20  ** literals may 
2ef50 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61  be replaced by a
2ef60 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61   [parameter] tha
2ef70 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66  t matches one of
2ef80 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65   following.** te
2ef90 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  mplates:.**.** <
2efa0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a  ul>.** <li>  ?.*
2efb0 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20  * <li>  ?NNN.** 
2efc0 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c  <li>  :VVV.** <l
2efd0 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  @VVV.** <li>
2efe0 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a    $VVV.** </ul>.
2eff0 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d  **.** In the tem
2f000 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e  plates above, NN
2f010 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  N represents an 
2f020 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c  integer literal,
2f030 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72  .** and VVV repr
2f040 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e  esents an alphan
2f050 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65  umeric identifie
2f060 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65  r.)^  ^The value
2f070 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61  s of these.** pa
2f080 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63  rameters (also c
2f090 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61  alled "host para
2f0a0 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20  meter names" or 
2f0b0 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22  "SQL parameters"
2f0c0 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20  ).** can be set 
2f0d0 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
2f0e0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
2f0f0 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65  nes defined here
2f100 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
2f110 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
2f120 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2f130 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20  *() routines is 
2f140 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e  always.** a poin
2f150 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
2f160 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
2f170 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a   returned from.*
2f180 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2f190 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20  re_v2()] or its 
2f1a0 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  variants..**.** 
2f1b0 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
2f1c0 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
2f1d0 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72  x of the SQL par
2f1e0 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74  ameter to be set
2f1f0 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f  ..** ^The leftmo
2f200 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  st SQL parameter
2f210 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
2f220 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73   1.  ^When the s
2f230 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c  ame named.** SQL
2f240 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73   parameter is us
2f250 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  ed more than onc
2f260 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75  e, second and su
2f270 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75  bsequent.** occu
2f280 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65  rrences have the
2f290 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74   same index as t
2f2a0 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65  he first occurre
2f2b0 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64  nce..** ^The ind
2f2c0 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72  ex for named par
2f2d0 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c  ameters can be l
2f2e0 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74  ooked up using t
2f2f0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  he.** [sqlite3_b
2f300 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2f310 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65  dex()] API if de
2f320 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64  sired.  ^The ind
2f330 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22  ex.** for "?NNN"
2f340 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74   parameters is t
2f350 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e  he value of NNN.
2f360 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c  .** ^The NNN val
2f370 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65  ue must be betwe
2f380 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71  en 1 and the [sq
2f390 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
2f3a0 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c  * parameter [SQL
2f3b0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
2f3c0 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61  LE_NUMBER] (defa
2f3d0 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e  ult value: 999).
2f3e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
2f3f0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
2f400 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20  e value to bind 
2f410 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
2f420 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69  ..** ^If the thi
2f430 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
2f440 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2f450 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  t() or sqlite3_b
2f460 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  ind_text16().** 
2f470 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
2f480 62 6c 6f 62 28 29 20 69 73 20 61 20 4e 55 4c 4c  blob() is a NULL
2f490 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68   pointer then th
2f4a0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2f4b0 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64  er.** is ignored
2f4c0 20 61 6e 64 20 74 68 65 20 65 6e 64 20 72 65 73   and the end res
2f4d0 75 6c 74 20 69 73 20 74 68 65 20 73 61 6d 65 20  ult is the same 
2f4e0 61 73 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  as sqlite3_bind_
2f4f0 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28  null()..**.** ^(
2f500 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65  In those routine
2f510 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f  s that have a fo
2f520 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69  urth argument, i
2f530 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  ts value is the.
2f540 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  ** number of byt
2f550 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  es in the parame
2f560 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61  ter.  To be clea
2f570 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  r: the value is 
2f580 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
2f590 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e   <u>bytes</u> in
2f5a0 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20   the value, not 
2f5b0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
2f5c0 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e  aracters.)^.** ^
2f5d0 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
2f5e0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2f5f0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f  e3_bind_text() o
2f600 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
2f610 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65  ext16().** is ne
2f620 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  gative, then the
2f630 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73   length of the s
2f640 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20  tring is.** the 
2f650 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2f660 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
2f670 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
2f680 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74  .** If the fourt
2f690 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
2f6a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2f6b0 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  () is negative, 
2f6c0 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61  then.** the beha
2f6d0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
2f6e0 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e  d..** If a non-n
2f6f0 65 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 70  egative fourth p
2f700 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76  arameter is prov
2f710 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f  ided to sqlite3_
2f720 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f  bind_text().** o
2f730 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
2f740 65 78 74 31 36 28 29 20 6f 72 20 73 71 6c 69 74  ext16() or sqlit
2f750 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29  e3_bind_text64()
2f760 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61   then.** that pa
2f770 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20  rameter must be 
2f780 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a  the byte offset.
2f790 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c  ** where the NUL
2f7a0 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c   terminator woul
2f7b0 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67  d occur assuming
2f7c0 20 74 68 65 20 73 74 72 69 6e 67 20 77 65 72 65   the string were
2f7d0 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74   NUL.** terminat
2f7e0 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20  ed.  If any NUL 
2f7f0 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72  characters occur
2f800 20 61 74 20 62 79 74 65 20 6f 66 66 73 65 74 73   at byte offsets
2f810 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74   less than .** t
2f820 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
2f830 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2f840 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
2f850 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65  ing string value
2f860 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e   will.** contain
2f870 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20   embedded NULs. 
2f880 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65   The result of e
2f890 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c  xpressions invol
2f8a0 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20  ving strings.** 
2f8b0 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55  with embedded NU
2f8c0 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  Ls is undefined.
2f8d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74  .**.** ^The fift
2f8e0 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  h argument to th
2f8f0 65 20 42 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e  e BLOB and strin
2f900 67 20 62 69 6e 64 69 6e 67 20 69 6e 74 65 72 66  g binding interf
2f910 61 63 65 73 0a 2a 2a 20 69 73 20 61 20 64 65 73  aces.** is a des
2f920 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20  tructor used to 
2f930 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42  dispose of the B
2f940 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67  LOB or.** string
2f950 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61   after SQLite ha
2f960 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
2f970 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75  it.  ^The destru
2f980 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a  ctor is called.*
2f990 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20  * to dispose of 
2f9a0 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  the BLOB or stri
2f9b0 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63  ng even if the c
2f9c0 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41 50 49 20  all to bind API 
2f9d0 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  fails..** ^If th
2f9e0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
2f9f0 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69   is.** the speci
2fa00 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  al value [SQLITE
2fa10 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53  _STATIC], then S
2fa20 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
2fa30 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d  at the.** inform
2fa40 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74  ation is in stat
2fa50 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70  ic, unmanaged sp
2fa60 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  ace and does not
2fa70 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65   need to be free
2fa80 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  d..** ^If the fi
2fa90 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73  fth argument has
2faa0 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49   the value [SQLI
2fab0 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74  TE_TRANSIENT], t
2fac0 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61  hen.** SQLite ma
2fad0 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76  kes its own priv
2fae0 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
2faf0 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79  data immediately
2fb00 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20  , before.** the 
2fb10 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2fb20 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2fb30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78  ..**.** ^The six
2fb40 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
2fb50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2fb60 36 34 28 29 20 6d 75 73 74 20 62 65 20 6f 6e 65  64() must be one
2fb70 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55   of.** [SQLITE_U
2fb80 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  TF8], [SQLITE_UT
2fb90 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  F16], [SQLITE_UT
2fba0 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49  F16BE], or [SQLI
2fbb0 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a 20 74  TE_UTF16LE].** t
2fbc0 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 65 6e  o specify the en
2fbd0 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20 74 65  coding of the te
2fbe0 78 74 20 69 6e 20 74 68 65 20 74 68 69 72 64 20  xt in the third 
2fbf0 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66 0a 2a  parameter.  If.*
2fc00 2a 20 74 68 65 20 73 69 78 74 68 20 61 72 67 75  * the sixth argu
2fc10 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
2fc20 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 69 73  bind_text64() is
2fc30 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a   not one of the.
2fc40 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65  ** allowed value
2fc50 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 2c 20 6f  s shown above, o
2fc60 72 20 69 66 20 74 68 65 20 74 65 78 74 20 65 6e  r if the text en
2fc70 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72  coding is differ
2fc80 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ent.** from the 
2fc90 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69  encoding specifi
2fca0 65 64 20 62 79 20 74 68 65 20 73 69 78 74 68 20  ed by the sixth 
2fcb0 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20  parameter, then 
2fcc0 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  the behavior.** 
2fcd0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
2fce0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2fcf0 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29  _bind_zeroblob()
2fd00 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61   routine binds a
2fd10 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20   BLOB of length 
2fd20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c  N that.** is fil
2fd30 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e  led with zeroes.
2fd40 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73    ^A zeroblob us
2fd50 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e  es a fixed amoun
2fd60 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28  t of memory.** (
2fd70 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20  just an integer 
2fd80 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65  to hold its size
2fd90 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65  ) while it is be
2fda0 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a  ing processed..*
2fdb0 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20  * Zeroblobs are 
2fdc0 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76  intended to serv
2fdd0 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72  e as placeholder
2fde0 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73  s for BLOBs whos
2fdf0 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20  e.** content is 
2fe00 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73  later written us
2fe10 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
2fe20 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72  blob_open | incr
2fe30 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f  emental BLOB I/O
2fe40 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e  ] routines..** ^
2fe50 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65  A negative value
2fe60 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f   for the zeroblo
2fe70 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a  b results in a z
2fe80 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e  ero-length BLOB.
2fe90 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f  .**.** ^If any o
2fea0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  f the sqlite3_bi
2feb0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
2fec0 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20  are called with 
2fed0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
2fee0 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61  * for the [prepa
2fef0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
2ff00 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65  r with a prepare
2ff10 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20  d statement for 
2ff20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65  which.** [sqlite
2ff30 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65  3_step()] has be
2ff40 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72  en called more r
2ff50 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71  ecently than [sq
2ff60 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a  lite3_reset()],.
2ff70 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** then the call
2ff80 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
2ff90 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49  LITE_MISUSE].  I
2ffa0 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69  f any sqlite3_bi
2ffb0 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  nd_().** routine
2ffc0 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72   is passed a [pr
2ffd0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2ffe0 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20  ] that has been 
2fff0 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a  finalized, the.*
30000 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  * result is unde
30010 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
30020 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a  ly harmful..**.*
30030 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20  * ^Bindings are 
30040 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74  not cleared by t
30050 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
30060 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  t()] routine..**
30070 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65   ^Unbound parame
30080 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72  ters are interpr
30090 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a  eted as NULL..**
300a0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
300b0 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73  _bind_* routines
300c0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
300d0 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f  OK] on success o
300e0 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  r an.** [error c
300f0 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67  ode] if anything
30100 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20   goes wrong..** 
30110 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d  ^[SQLITE_TOOBIG]
30120 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
30130 65 64 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f  ed if the size o
30140 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  f a string or BL
30150 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c 69  OB.** exceeds li
30160 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62 79 20  mits imposed by 
30170 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28  [sqlite3_limit](
30180 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  [SQLITE_LIMIT_LE
30190 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51  NGTH]) or.** [SQ
301a0 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d  LITE_MAX_LENGTH]
301b0 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41  ..** ^[SQLITE_RA
301c0 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64  NGE] is returned
301d0 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
301e0 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75  r.** index is ou
301f0 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53  t of range.  ^[S
30200 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20  QLITE_NOMEM] is 
30210 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c  returned if mall
30220 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  oc() fails..**.*
30230 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
30240 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
30250 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a  ter_count()],.**
30260 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
30270 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
30280 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  , and [sqlite3_b
30290 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
302a0 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  dex()]..*/.SQLIT
302b0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
302c0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
302d0 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74  _bind_blob(sqlit
302e0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
302f0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
30300 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
30310 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  ));.SQLITE_API i
30320 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
30330 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  L sqlite3_bind_b
30340 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74  lob64(sqlite3_st
30350 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
30360 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75  void*, sqlite3_u
30370 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20  int64,.         
30380 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
30390 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
303a0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
303b0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
303c0 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c  lite3_bind_doubl
303d0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
303e0 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 53   int, double);.S
303f0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
30400 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
30410 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71  ite3_bind_int(sq
30420 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
30430 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  , int);.SQLITE_A
30440 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
30450 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69  DCALL sqlite3_bi
30460 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  nd_int64(sqlite3
30470 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c  _stmt*, int, sql
30480 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c  ite3_int64);.SQL
30490 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
304a0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
304b0 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c  e3_bind_null(sql
304c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
304d0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
304e0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
304f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
30500 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
30510 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
30520 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
30530 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  *));.SQLITE_API 
30540 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
30550 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  LL sqlite3_bind_
30560 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
30570 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
30580 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
30590 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51  d(*)(void*));.SQ
305a0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
305b0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
305c0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28  te3_bind_text64(
305d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
305e0 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  nt, const char*,
305f0 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c   sqlite3_uint64,
30600 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
30610 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a            void(*
30620 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e  )(void*), unsign
30630 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69 6e 67  ed char encoding
30640 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
30650 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
30660 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61   sqlite3_bind_va
30670 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
30680 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71  *, int, const sq
30690 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
306a0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
306b0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
306c0 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
306d0 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
306e0 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 53  , int, int n);.S
306f0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
30700 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
30710 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
30720 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  ob64(sqlite3_stm
30730 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33  t*, int, sqlite3
30740 5f 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a  _uint64);../*.**
30750 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
30760 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74  r Of SQL Paramet
30770 65 72 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ers.** METHOD: s
30780 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
30790 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
307a0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66  can be used to f
307b0 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ind the number o
307c0 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  f [SQL parameter
307d0 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70  s].** in a [prep
307e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
307f0 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73    SQL parameters
30800 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74   are tokens of t
30810 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20  he.** form "?", 
30820 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20  "?NNN", ":AAA", 
30830 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41  "$AAA", or "@AAA
30840 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a  " that serve as.
30850 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20  ** placeholders 
30860 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20  for values that 
30870 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  are [sqlite3_bin
30880 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a  d_blob | bound].
30890 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  ** to the parame
308a0 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20  ters at a later 
308b0 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  time..**.** ^(Th
308c0 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61  is routine actua
308d0 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20  lly returns the 
308e0 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72  index of the lar
308f0 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29  gest (rightmost)
30900 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46  .** parameter. F
30910 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63  or all forms exc
30920 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77  ept ?NNN, this w
30930 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74  ill correspond t
30940 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  o the.** number 
30950 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65  of unique parame
30960 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65  ters.  If parame
30970 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e  ters of the ?NNN
30980 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a   form are used,.
30990 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20  ** there may be 
309a0 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74  gaps in the list
309b0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  .)^.**.** See al
309c0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
309d0 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
309e0 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
309f0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
30a00 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a  er_name()], and.
30a10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
30a20 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
30a30 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
30a40 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
30a50 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69  DCALL sqlite3_bi
30a60 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
30a70 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
30a80 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
30a90 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f  EF: Name Of A Ho
30aa0 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20  st Parameter.** 
30ab0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
30ac0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
30ad0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
30ae0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29  ameter_name(P,N)
30af0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
30b00 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  ns.** the name o
30b10 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20  f the N-th [SQL 
30b20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
30b30 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
30b40 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53  ement] P..** ^(S
30b50 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  QL parameters of
30b60 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22   the form "?NNN"
30b70 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
30b80 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
30b90 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68  * have a name wh
30ba0 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e  ich is the strin
30bb0 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  g "?NNN" or ":AA
30bc0 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
30bd0 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63  "$AAA".** respec
30be0 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74  tively..** In ot
30bf0 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69  her words, the i
30c00 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24  nitial ":" or "$
30c10 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a  " or "@" or "?".
30c20 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61  ** is included a
30c30 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61  s part of the na
30c40 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65  me.)^.** ^Parame
30c50 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
30c60 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66   "?" without a f
30c70 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72  ollowing integer
30c80 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a   have no name.**
30c90 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65   and are referre
30ca0 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73  d to as "nameles
30cb0 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73  s" or "anonymous
30cc0 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a   parameters"..**
30cd0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68  .** ^The first h
30ce0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61  ost parameter ha
30cf0 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c  s an index of 1,
30d00 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49   not 0..**.** ^I
30d10 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73  f the value N is
30d20 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72   out of range or
30d30 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72   if the N-th par
30d40 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d  ameter is.** nam
30d50 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c  eless, then NULL
30d60 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e   is returned.  ^
30d70 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
30d80 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73  ing is.** always
30d90 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69   in UTF-8 encodi
30da0 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e  ng even if the n
30db0 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77  amed parameter w
30dc0 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79  as.** originally
30dd0 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54   specified as UT
30de0 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33  F-16 in [sqlite3
30df0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72  _prepare16()] or
30e00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
30e10 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
30e20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
30e30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
30e40 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
30e50 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
30e60 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
30e70 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
30e80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
30e90 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
30ea0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
30eb0 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45  nst char *SQLITE
30ec0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
30ed0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
30ee0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
30ef0 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  t*, int);../*.**
30f00 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78   CAPI3REF: Index
30f10 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20   Of A Parameter 
30f20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d  With A Given Nam
30f30 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  e.** METHOD: sql
30f40 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
30f50 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65  ^Return the inde
30f60 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61  x of an SQL para
30f70 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20  meter given its 
30f80 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69  name.  ^The.** i
30f90 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72  ndex value retur
30fa0 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20  ned is suitable 
30fb0 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73  for use as the s
30fc0 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74  econd.** paramet
30fd0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  er to [sqlite3_b
30fe0 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
30ff0 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65  _bind()].  ^A ze
31000 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  ro.** is returne
31010 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67  d if no matching
31020 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f   parameter is fo
31030 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d  und.  ^The param
31040 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73  eter.** name mus
31050 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54  t be given in UT
31060 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20  F-8 even if the 
31070 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
31080 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72  nt.** was prepar
31090 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74  ed from UTF-16 t
310a0 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ext using [sqlit
310b0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
310c0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
310d0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
310e0 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
310f0 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
31100 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
31110 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
31120 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
31130 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
31140 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
31150 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
31160 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69  DCALL sqlite3_bi
31170 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
31180 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ex(sqlite3_stmt*
31190 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
311a0 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ame);../*.** CAP
311b0 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c  I3REF: Reset All
311c0 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50   Bindings On A P
311d0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
311e0 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
311f0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
31200 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65  ^Contrary to the
31210 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61   intuition of ma
31220 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ny, [sqlite3_res
31230 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72  et()] does not r
31240 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  eset.** the [sql
31250 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
31260 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20   bindings] on a 
31270 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
31280 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68  ent]..** ^Use th
31290 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65  is routine to re
312a0 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72  set all host par
312b0 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e  ameters to NULL.
312c0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
312d0 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
312e0 4c 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f  L sqlite3_clear_
312f0 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
31300 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
31310 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
31320 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41   Of Columns In A
31330 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d   Result Set.** M
31340 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
31350 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72  tmt.**.** ^Retur
31360 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  n the number of 
31370 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
31380 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e  esult set return
31390 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72  ed by the.** [pr
313a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
313b0 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ]. ^This routine
313c0 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53   returns 0 if pS
313d0 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a  tmt is an SQL.**
313e0 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
313f0 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20  does not return 
31400 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c  data (for exampl
31410 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a  e an [UPDATE])..
31420 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
31430 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f  [sqlite3_data_co
31440 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45  unt()].*/.SQLITE
31450 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
31460 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
31470 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c  column_count(sql
31480 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
31490 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
314a0 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73  EF: Column Names
314b0 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
314c0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
314d0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
314e0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
314f0 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61  eturn the name a
31500 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72  ssigned to a par
31510 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a  ticular column.*
31520 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  * in the result 
31530 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
31540 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54  ] statement.  ^T
31550 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
31560 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65  n_name().** inte
31570 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
31580 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
31590 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
315a0 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64  -8 string.** and
315b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
315c0 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73  name16() returns
315d0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
315e0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
315f0 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
31600 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  .  ^The first pa
31610 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
31620 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
31630 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c  nt].** that impl
31640 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45  ements the [SELE
31650 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e  CT] statement. ^
31660 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
31670 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63  eter is the.** c
31680 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e  olumn number.  ^
31690 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
316a0 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e  umn is number 0.
316b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  .**.** ^The retu
316c0 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e  rned string poin
316d0 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ter is valid unt
316e0 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70  il either the [p
316f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
31700 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79  t].** is destroy
31710 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
31720 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
31730 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e  til the statemen
31740 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  t is automatical
31750 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64  ly.** reprepared
31760 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61   by the first ca
31770 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
31780 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72  tep()] for a par
31790 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f  ticular run.** o
317a0 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74  r until the next
317b0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
317c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
317d0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
317e0 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20  umn_name16() on 
317f0 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e  the same column.
31800 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  .**.** ^If sqlit
31810 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  e3_malloc() fail
31820 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f  s during the pro
31830 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65  cessing of eithe
31840 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f  r routine.** (fo
31850 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67  r example during
31860 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72   a conversion fr
31870 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d  om UTF-8 to UTF-
31880 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55  16) then a.** NU
31890 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
318a0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
318b0 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73  he name of a res
318c0 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68  ult column is th
318d0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22  e value of the "
318e0 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a  AS" clause for.*
318f0 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69  * that column, i
31900 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53  f there is an AS
31910 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65   clause.  If the
31920 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75  re is no AS clau
31930 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e  se.** then the n
31940 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  ame of the colum
31950 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64  n is unspecified
31960 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20   and may change 
31970 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65  from.** one rele
31980 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f  ase of SQLite to
31990 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 53 51   the next..*/.SQ
319a0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
319b0 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  har *SQLITE_STDC
319c0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ALL sqlite3_colu
319d0 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  mn_name(sqlite3_
319e0 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53  stmt*, int N);.S
319f0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
31a00 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44  void *SQLITE_STD
31a10 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  CALL sqlite3_col
31a20 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  umn_name16(sqlit
31a30 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
31a40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
31a50 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74  F: Source Of Dat
31a60 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73  a In A Query Res
31a70 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ult.** METHOD: s
31a80 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
31a90 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
31aa0 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e  s provide a mean
31ab0 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74  s to determine t
31ac0 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  he database, tab
31ad0 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65  le, and.** table
31ae0 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20   column that is 
31af0 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20  the origin of a 
31b00 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c  particular resul
31b10 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b  t column in.** [
31b20 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
31b30 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  t..** ^The name 
31b40 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
31b50 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75  or table or colu
31b60 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e  mn can be return
31b70 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20  ed as.** either 
31b80 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  a UTF-8 or UTF-1
31b90 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
31ba0 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69  _database_ routi
31bb0 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68  nes return.** th
31bc0 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c  e database name,
31bd0 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75   the _table_ rou
31be0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
31bf0 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64   table name, and
31c00 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20  .** the origin_ 
31c10 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
31c20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e  the column name.
31c30 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
31c40 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69  d string is vali
31c50 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65  d until the [pre
31c60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
31c70 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a   is destroyed.**
31c80 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
31c90 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
31ca0 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65  ntil the stateme
31cb0 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  nt is automatica
31cc0 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65  lly.** reprepare
31cd0 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63  d by the first c
31ce0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
31cf0 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61  step()] for a pa
31d00 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20  rticular run.** 
31d10 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d  or until the sam
31d20 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  e information is
31d30 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67   requested.** ag
31d40 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65  ain in a differe
31d50 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a  nt encoding..**.
31d60 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65  ** ^The names re
31d70 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f  turned are the o
31d80 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73  riginal un-alias
31d90 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a  ed names of the.
31da0 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ** database, tab
31db0 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a  le, and column..
31dc0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
31dd0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
31de0 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73  se interfaces is
31df0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
31e00 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65  tement]..** ^The
31e10 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
31e20 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
31e30 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65  about the Nth re
31e40 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75  sult column retu
31e50 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73  rned by.** the s
31e60 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20  tatement, where 
31e70 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
31e80 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
31e90 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d  t..** ^The left-
31ea0 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63  most column is c
31eb0 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73  olumn 0 for thes
31ec0 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
31ed0 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f  * ^If the Nth co
31ee0 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
31ef0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
31f00 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20  s an expression 
31f10 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61  or.** subquery a
31f20 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75  nd is not a colu
31f30 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61  mn value, then a
31f40 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  ll of these func
31f50 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tions return.** 
31f60 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f  NULL.  ^These ro
31f70 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f  utine might also
31f80 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20   return NULL if 
31f90 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
31fa0 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63  ion error.** occ
31fb0 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65  urs.  ^Otherwise
31fc0 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68  , they return th
31fd0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74  e name of the at
31fe0 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c  tached database,
31ff0 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f   table,.** or co
32000 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20  lumn that query 
32010 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61  result column wa
32020 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d  s extracted from
32030 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68  ..**.** ^As with
32040 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74   all other SQLit
32050 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68  e APIs, those wh
32060 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69  ose names end wi
32070 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a  th "16" return.*
32080 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  * UTF-16 encoded
32090 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65   strings and the
320a0 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73   other functions
320b0 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a   return UTF-8..*
320c0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73  *.** ^These APIs
320d0 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61   are only availa
320e0 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61  ble if the libra
320f0 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  ry was compiled 
32100 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
32110 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d  ITE_ENABLE_COLUM
32120 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72  N_METADATA] C-pr
32130 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f  eprocessor symbo
32140 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  l..**.** If two 
32150 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
32160 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
32170 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
32180 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73  es against the s
32190 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  ame.** prepared 
321a0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f  statement and co
321b0 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65  lumn at the same
321c0 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
321d0 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e  esults are.** un
321e0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  defined..**.** I
321f0 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
32200 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
32210 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74  r more.** [sqlit
32220 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
32230 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e  se_name | column
32240 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66   metadata interf
32250 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65  aces].** for the
32260 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
32270 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72  statement] and r
32280 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  esult column.** 
32290 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
322a0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
322b0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
322c0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
322d0 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54  onst char *SQLIT
322e0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
322f0 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
32300 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
32310 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54  tmt*,int);.SQLIT
32320 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
32330 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
32340 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
32350 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28  database_name16(
32360 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
32370 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
32380 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54  onst char *SQLIT
32390 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
323a0 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
323b0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
323c0 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
323d0 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53  PI const void *S
323e0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
323f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
32400 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  le_name16(sqlite
32410 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51  3_stmt*,int);.SQ
32420 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
32430 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  har *SQLITE_STDC
32440 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ALL sqlite3_colu
32450 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73  mn_origin_name(s
32460 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
32470 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
32480 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45  nst void *SQLITE
32490 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
324a0 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
324b0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
324c0 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
324d0 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61   CAPI3REF: Decla
324e0 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20  red Datatype Of 
324f0 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
32500 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
32510 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54  3_stmt.**.** ^(T
32520 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
32530 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  er is a [prepare
32540 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
32550 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65   If this stateme
32560 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d  nt is a [SELECT]
32570 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
32580 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
32590 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64   the.** returned
325a0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
325b0 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20  hat [SELECT] is 
325c0 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28  a table column (
325d0 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73  not an.** expres
325e0 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
325f0 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61  ) then the decla
32600 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20  red type of the 
32610 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  table.** column 
32620 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20  is returned.)^  
32630 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  ^If the Nth colu
32640 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
32650 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78   set is an.** ex
32660 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
32670 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c  uery, then a NUL
32680 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
32690 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72  urned..** ^The r
326a0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
326b0 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65  s always UTF-8 e
326c0 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ncoded..**.** ^(
326d0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76  For example, giv
326e0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
326f0 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52  schema:.**.** CR
32700 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31  EATE TABLE t1(c1
32710 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a   VARIANT);.**.**
32720 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69   and the followi
32730 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  ng statement to 
32740 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a  be compiled:.**.
32750 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31  ** SELECT c1 + 1
32760 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a  , c1 FROM t1;.**
32770 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
32780 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68   would return th
32790 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e  e string "VARIAN
327a0 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e  T" for the secon
327b0 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75  d result.** colu
327c0 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61  mn (i==1), and a
327d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
327e0 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75  r the first resu
327f0 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29  lt column (i==0)
32800 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  .)^.**.** ^SQLit
32810 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72  e uses dynamic r
32820 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20  un-time typing. 
32830 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73   ^So just becaus
32840 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  e a column.** is
32850 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e   declared to con
32860 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61  tain a particula
32870 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20  r type does not 
32880 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a  mean that the.**
32890 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20   data stored in 
328a0 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f  that column is o
328b0 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  f the declared t
328c0 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a  ype.  SQLite is.
328d0 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65  ** strongly type
328e0 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e  d, but the typin
328f0 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74  g is dynamic not
32900 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a   static.  ^Type.
32910 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  ** is associated
32920 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c   with individual
32930 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74   values, not wit
32940 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73  h the containers
32950 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  .** used to hold
32960 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a   those values..*
32970 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
32980 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f  st char *SQLITE_
32990 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
329a0 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28  column_decltype(
329b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
329c0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
329d0 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54  onst void *SQLIT
329e0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
329f0 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
32a00 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
32a10 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
32a20 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74  API3REF: Evaluat
32a30 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  e An SQL Stateme
32a40 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  nt.** METHOD: sq
32a50 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
32a60 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72   After a [prepar
32a70 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61  ed statement] ha
32a80 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20  s been prepared 
32a90 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20  using either.** 
32aa0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
32ab0 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
32ac0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
32ad0 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  )] or one of the
32ae0 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
32af0 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70  faces [sqlite3_p
32b00 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71  repare()] or [sq
32b10 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
32b20 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  )], this functio
32b30 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c  n.** must be cal
32b40 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  led one or more 
32b50 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74  times to evaluat
32b60 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e  e the statement.
32b70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69  .**.** The detai
32b80 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69  ls of the behavi
32b90 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  or of the sqlite
32ba0 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61  3_step() interfa
32bb0 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20  ce depend.** on 
32bc0 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74  whether the stat
32bd0 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72  ement was prepar
32be0 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77  ed using the new
32bf0 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  er "v2" interfac
32c00 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
32c10 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
32c20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
32c30 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20  16_v2()] or the 
32c40 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20  older legacy.** 
32c50 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74  interface [sqlit
32c60 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
32c70 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
32c80 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73  re16()].  The us
32c90 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20  e of the.** new 
32ca0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
32cb0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
32cc0 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  r new applicatio
32cd0 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63  ns but the legac
32ce0 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77  y.** interface w
32cf0 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ill continue to 
32d00 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a  be supported..**
32d10 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61  .** ^In the lega
32d20 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
32d30 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77  e return value w
32d40 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53  ill be either [S
32d50 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20  QLITE_BUSY],.** 
32d60 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b  [SQLITE_DONE], [
32d70 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51  SQLITE_ROW], [SQ
32d80 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20  LITE_ERROR], or 
32d90 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
32da0 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76  .** ^With the "v
32db0 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e  2" interface, an
32dc0 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b  y of the other [
32dd0 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72  result codes] or
32de0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
32df0 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68  sult codes] migh
32e00 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  t be returned as
32e10 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   well..**.** ^[S
32e20 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e  QLITE_BUSY] mean
32e30 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62  s that the datab
32e40 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75  ase engine was u
32e50 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65  nable to acquire
32e60 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
32e70 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20   locks it needs 
32e80 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20  to do its job.  
32e90 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ^If the statemen
32ea0 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a  t is a [COMMIT].
32eb0 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74  ** or occurs out
32ec0 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69  side of an expli
32ed0 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
32ee0 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65   then you can re
32ef0 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  try the.** state
32f00 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74  ment.  If the st
32f10 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61  atement is not a
32f20 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63   [COMMIT] and oc
32f30 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a  curs within an.*
32f40 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  * explicit trans
32f50 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20  action then you 
32f60 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20  should rollback 
32f70 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
32f80 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e  before.** contin
32f90 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  uing..**.** ^[SQ
32fa0 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73  LITE_DONE] means
32fb0 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d   that the statem
32fc0 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64  ent has finished
32fd0 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75   executing.** su
32fe0 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c  ccessfully.  sql
32ff0 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
33000 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
33010 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76   again on this v
33020 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
33030 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20  e without first 
33040 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
33050 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73  _reset()] to res
33060 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a  et the virtual.*
33070 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74  * machine back t
33080 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
33090 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ate..**.** ^If t
330a0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
330b0 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20   being executed 
330c0 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61  returns any data
330d0 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52  , then [SQLITE_R
330e0 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  OW].** is return
330f0 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e  ed each time a n
33100 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69  ew row of data i
33110 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63  s ready for proc
33120 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a  essing by the.**
33130 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c   caller. The val
33140 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73  ues may be acces
33150 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63  sed using the [c
33160 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
33170 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69  ctions]..** sqli
33180 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61  te3_step() is ca
33190 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65  lled again to re
331a0 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20  trieve the next 
331b0 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  row of data..**.
331c0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ** ^[SQLITE_ERRO
331d0 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20  R] means that a 
331e0 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28  run-time error (
331f0 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72  such as a constr
33200 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f  aint.** violatio
33210 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e  n) has occurred.
33220 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
33230 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
33240 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a  alled again on.*
33250 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69  * the VM. More i
33260 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62  nformation may b
33270 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69  e found by calli
33280 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ng [sqlite3_errm
33290 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  sg()]..** ^With 
332a0 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
332b0 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65  face, a more spe
332c0 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
332d0 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a   (for example,.*
332e0 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  * [SQLITE_INTERR
332f0 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43  UPT], [SQLITE_SC
33300 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43  HEMA], [SQLITE_C
33310 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20  ORRUPT], and so 
33320 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65  forth).** can be
33330 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c   obtained by cal
33340 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
33350 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a  set()] on the.**
33360 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
33370 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20  ment].  ^In the 
33380 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a  "v2" interface,.
33390 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  ** the more spec
333a0 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
333b0 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  is returned dire
333c0 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ctly by sqlite3_
333d0 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53  step()..**.** [S
333e0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65  QLITE_MISUSE] me
333f0 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69  ans that the thi
33400 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61  s routine was ca
33410 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61  lled inappropria
33420 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73  tely..** Perhaps
33430 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f   it was called o
33440 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
33450 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
33460 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65  s.** already bee
33470 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  n [sqlite3_final
33480 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d  ize | finalized]
33490 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20   or on one that 
334a0 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  had.** previousl
334b0 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  y returned [SQLI
334c0 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51  TE_ERROR] or [SQ
334d0 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20  LITE_DONE].  Or 
334e0 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74  it could.** be t
334f0 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
33500 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
33510 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69  onnection is bei
33520 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f  ng used by two o
33530 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64  r.** more thread
33540 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f  s at the same mo
33550 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a  ment in time..**
33560 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73  .** For all vers
33570 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75  ions of SQLite u
33580 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69  p to and includi
33590 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63  ng 3.6.23.1, a c
335a0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
335b0 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20  e3_reset()] was 
335c0 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20 73  required after s
335d0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 65  qlite3_step() re
335e0 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a  turned anything.
335f0 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ** other than [S
33600 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72  QLITE_ROW] befor
33610 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74  e any subsequent
33620 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a   invocation of.*
33630 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
33640 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65  .  Failure to re
33650 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
33660 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
33670 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65   .** [sqlite3_re
33680 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73  set()] would res
33690 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54  ult in an [SQLIT
336a0 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e  E_MISUSE] return
336b0 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33   from.** sqlite3
336c0 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 66  _step().  But af
336d0 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e  ter version 3.6.
336e0 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 74  23.1, sqlite3_st
336f0 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61  ep() began.** ca
33700 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
33710 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69  eset()] automati
33720 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69  cally in this ci
33730 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65  rcumstance rathe
33740 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e  r.** than return
33750 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  ing [SQLITE_MISU
33760 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f  SE].  This is no
33770 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63  t considered a c
33780 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20  ompatibility.** 
33790 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e  break because an
337a0 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68  y application th
337b0 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73  at ever receives
337c0 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53   an SQLITE_MISUS
337d0 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72  E error.** is br
337e0 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69  oken by definiti
337f0 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  on.  The [SQLITE
33800 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d  _OMIT_AUTORESET]
33810 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
33820 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75  tion.** can be u
33830 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74  sed to restore t
33840 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
33850 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f  or..**.** <b>Goo
33860 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65  fy Interface Ale
33870 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c  rt:</b> In the l
33880 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
33890 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
338a0 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79  p().** API alway
338b0 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65  s returns a gene
338c0 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20  ric error code, 
338d0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
338e0 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a  following any.**
338f0 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61   error other tha
33900 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
33910 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  and [SQLITE_MISU
33920 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63  SE].  You must c
33930 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  all.** [sqlite3_
33940 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
33950 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
33960 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
33970 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  d one of the.** 
33980 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
33990 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74  codes] that bett
339a0 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65  er describes the
339b0 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64   error..** We ad
339c0 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73  mit that this is
339d0 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e   a goofy design.
339e0 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61    The problem ha
339f0 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20  s been fixed.** 
33a00 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  with the "v2" in
33a10 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75  terface.  If you
33a20 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20   prepare all of 
33a30 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65  your SQL stateme
33a40 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74  nts.** using eit
33a50 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
33a60 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
33a70 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
33a80 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a  _v2()] instead.*
33a90 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20  * of the legacy 
33aa0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
33ab0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
33ac0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e  _prepare16()] in
33ad0 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65  terfaces,.** the
33ae0 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  n the more speci
33af0 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
33b00 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64  ] are returned d
33b10 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71  irectly.** by sq
33b20 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54  lite3_step().  T
33b30 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76  he use of the "v
33b40 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
33b50 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a  recommended..*/.
33b60 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
33b70 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
33b80 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74  lite3_step(sqlit
33b90 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
33ba0 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
33bb0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
33bc0 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a   a result set.**
33bd0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
33be0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
33bf0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
33c00 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65  unt(P) interface
33c10 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
33c20 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
33c30 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  n the.** current
33c40 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
33c50 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61  lt set of [prepa
33c60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50  red statement] P
33c70 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65  ..** ^If prepare
33c80 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f  d statement P do
33c90 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75  es not have resu
33ca0 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74  lts ready to ret
33cb0 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c  urn.** (via call
33cc0 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  s to the [sqlite
33cd0 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73  3_column_int | s
33ce0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28  qlite3_column_*(
33cf0 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61  )] of.** interfa
33d00 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65  ces) then sqlite
33d10 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
33d20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54  returns 0..** ^T
33d30 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
33d40 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65  count(P) routine
33d50 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20   also returns 0 
33d60 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70  if P is a NULL p
33d70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  ointer..** ^The 
33d80 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
33d90 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65  nt(P) routine re
33da0 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 20 70  turns 0 if the p
33db0 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a  revious call to.
33dc0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
33dd0 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53  ](P) returned [S
33de0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54  QLITE_DONE].  ^T
33df0 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
33e00 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c  count(P).** will
33e10 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f   return non-zero
33e20 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c   if previous cal
33e30 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
33e40 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a  ep](P) returned.
33e50 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ** [SQLITE_ROW],
33e60 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 20 63   except in the c
33e70 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47  ase of the [PRAG
33e80 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76  MA incremental_v
33e90 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20  acuum].** where 
33ea0 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  it always return
33eb0 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63  s zero since eac
33ec0 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d  h step of that m
33ed0 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61  ulti-step.** pra
33ee0 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f  gma returns 0 co
33ef0 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a  lumns of data..*
33f00 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
33f10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
33f20 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54  ount()].*/.SQLIT
33f30 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
33f40 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
33f50 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69  _data_count(sqli
33f60 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
33f70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33f80 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44  F: Fundamental D
33f90 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57  atatypes.** KEYW
33fa0 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58  ORDS: SQLITE_TEX
33fb0 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20  T.**.** ^(Every 
33fc0 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20  value in SQLite 
33fd0 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20  has one of five 
33fe0 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61  fundamental data
33ff0 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  types:.**.** <ul
34000 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  >.** <li> 64-bit
34010 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
34020 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49  ** <li> 64-bit I
34030 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  EEE floating poi
34040 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69  nt number.** <li
34050 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e  > string.** <li>
34060 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55   BLOB.** <li> NU
34070 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  LL.** </ul>)^.**
34080 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
34090 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f  nts are codes fo
340a0 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20  r each of those 
340b0 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  types..**.** Not
340c0 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54  e that the SQLIT
340d0 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20  E_TEXT constant 
340e0 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e  was also used in
340f0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
34100 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c  2.** for a compl
34110 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20  etely different 
34120 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61  meaning.  Softwa
34130 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67  re that links ag
34140 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51  ainst both.** SQ
34150 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61  Lite version 2 a
34160 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
34170 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53  n 3 should use S
34180 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74  QLITE3_TEXT, not
34190 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e  .** SQLITE_TEXT.
341a0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
341b0 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64  TE_INTEGER  1.#d
341c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f  efine SQLITE_FLO
341d0 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  AT    2.#define 
341e0 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20  SQLITE_BLOB     
341f0 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
34200 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64  _NULL     5.#ifd
34210 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
34220 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45   undef SQLITE_TE
34230 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e  XT.#else.# defin
34240 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20  e SQLITE_TEXT   
34250 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69    3.#endif.#defi
34260 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20  ne SQLITE3_TEXT 
34270 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      3../*.** CAP
34280 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61  I3REF: Result Va
34290 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72  lues From A Quer
342a0 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  y.** KEYWORDS: {
342b0 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
342c0 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48  nctions}.** METH
342d0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
342e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
342f0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e  utines return in
34300 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
34310 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20  a single column 
34320 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  of the current.*
34330 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20  * result row of 
34340 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76  a query.  ^In ev
34350 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72  ery case the fir
34360 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
34370 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
34380 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
34390 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20  tement] that is 
343a0 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20  being evaluated 
343b0 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
343c0 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73  mt*].** that was
343d0 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b   returned from [
343e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
343f0 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
34400 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a  its variants).**
34410 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
34420 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
34430 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c  index of the col
34440 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e  umn for which in
34450 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  formation.** sho
34460 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
34470 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
34480 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
34490 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20  ult set has the 
344a0 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65  index 0..** ^The
344b0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
344c0 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
344d0 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
344e0 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
344f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
34500 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  t()]..**.** If t
34510 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
34520 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e   does not curren
34530 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76  tly point to a v
34540 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20  alid row, or if 
34550 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e  the.** column in
34560 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
34570 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20  nge, the result 
34580 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
34590 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
345a0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  may only be call
345b0 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74  ed when the most
345c0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a   recent call to.
345d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
345e0 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
345f0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e   [SQLITE_ROW] an
34600 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  d neither.** [sq
34610 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e  lite3_reset()] n
34620 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
34630 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65  lize()] have bee
34640 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75  n called subsequ
34650 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79  ently..** If any
34660 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
34670 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66  es are called af
34680 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ter [sqlite3_res
34690 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
346a0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
346b0 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74   or after [sqlit
346c0 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
346d0 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74  eturned.** somet
346e0 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
346f0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68  [SQLITE_ROW], th
34700 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
34710 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b  defined..** If [
34720 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
34730 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
34740 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
34750 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20  _finalize()].** 
34760 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
34770 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  a different thre
34780 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20  ad while any of 
34790 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
347a0 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74  * are pending, t
347b0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
347c0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
347d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
347e0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
347f0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
34800 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  the.** [SQLITE_I
34810 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
34820 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  e code] for the 
34830 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70  initial data typ
34840 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  e.** of the resu
34850 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65  lt column.  ^The
34860 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20   returned value 
34870 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
34880 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b  E_INTEGER],.** [
34890 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b  SQLITE_FLOAT], [
348a0 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53  SQLITE_TEXT], [S
348b0 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20  QLITE_BLOB], or 
348c0 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20  [SQLITE_NULL].  
348d0 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  The value.** ret
348e0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
348f0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
34900 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75  s only meaningfu
34910 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20  l if no type.** 
34920 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65  conversions have
34930 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73   occurred as des
34940 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41  cribed below.  A
34950 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76  fter a type conv
34960 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76  ersion,.** the v
34970 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
34980 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
34990 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69  type() is undefi
349a0 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20  ned.  Future.** 
349b0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
349c0 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68  te may change th
349d0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71  e behavior of sq
349e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
349f0 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  e().** following
34a00 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
34a10 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  on..**.** ^If th
34a20 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
34a30 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69  OB or UTF-8 stri
34a40 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
34a50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
34a60 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
34a70 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
34a80 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
34a90 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
34aa0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
34ab0 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20  ult is a UTF-16 
34ac0 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
34ad0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
34ae0 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  s() converts.** 
34af0 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
34b00 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74  F-8 and then ret
34b10 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
34b20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66  of bytes..** ^If
34b30 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
34b40 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
34b50 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
34b60 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a  mn_bytes() uses.
34b70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
34b80 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
34b90 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
34ba0 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20   a UTF-8 string 
34bb0 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
34bc0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
34bd0 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
34be0 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
34bf0 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
34c00 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
34c10 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e  n_bytes() return
34c20 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49  s zero..**.** ^I
34c30 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
34c40 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36  a BLOB or UTF-16
34c50 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
34c60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
34c70 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75  bytes16().** rou
34c80 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
34c90 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
34ca0 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
34cb0 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
34cc0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
34cd0 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68  UTF-8 string, th
34ce0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
34cf0 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76  n_bytes16() conv
34d00 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
34d10 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64  ng to UTF-16 and
34d20 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
34d30 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
34d40 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
34d50 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
34d60 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
34d70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
34d80 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  s16() uses.** [s
34d90 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
34da0 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
34db0 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
34dc0 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20  F-16 string and 
34dd0 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
34de0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
34df0 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
34e00 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
34e10 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
34e20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
34e30 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20  tes16() returns 
34e40 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  zero..**.** ^The
34e50 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
34e60 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
34e70 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64  umn_bytes()] and
34e80 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f   .** [sqlite3_co
34e90 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20  lumn_bytes16()] 
34ea0 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74  do not include t
34eb0 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
34ec0 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a  ors at the end.*
34ed0 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e  * of the string.
34ee0 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20    ^For clarity: 
34ef0 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  the values retur
34f00 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
34f10 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
34f20 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
34f30 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
34f40 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72  ] are the number
34f50 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20   of.** bytes in 
34f60 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20  the string, not 
34f70 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
34f80 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
34f90 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65  ^Strings returne
34fa0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
34fb0 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73  umn_text() and s
34fc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
34fd0 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20  xt16(),.** even 
34fe0 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61  empty strings, a
34ff0 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  re always zero-t
35000 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
35010 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
35020 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
35030 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20  lumn_blob() for 
35040 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
35050 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  OB is a NULL poi
35060 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57  nter..**.** <b>W
35070 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65  arning:</b> ^The
35080 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
35090 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
350a0 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
350b0 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
350c0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
350d0 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61 20  ] object.  In a 
350e0 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 65 6e  multithreaded en
350f0 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e  vironment,.** an
35100 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
35110 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
35120 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  t may only be us
35130 65 64 20 73 61 66 65 6c 79 20 77 69 74 68 0a 2a  ed safely with.*
35140 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
35150 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
35160 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
35170 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65  ue()]..** If the
35180 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
35190 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
351a0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
351b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
351c0 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
351d0 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72  sed in any other
351e0 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20   way, including 
351f0 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74  calls.** to rout
35200 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
35210 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c  e3_value_int()],
35220 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
35230 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
35240 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
35250 74 65 73 28 29 5d 2c 20 74 68 65 20 62 65 68 61  tes()], the beha
35260 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 68 72 65  vior is not thre
35270 61 64 73 61 66 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  adsafe..**.** Th
35280 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74  ese routines att
35290 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20  empt to convert 
352a0 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20  the value where 
352b0 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46  appropriate.  ^F
352c0 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69  or.** example, i
352d0 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  f the internal r
352e0 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73  epresentation is
352f0 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78   FLOAT and a tex
35300 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72  t result.** is r
35310 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74  equested, [sqlit
35320 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69  e3_snprintf()] i
35330 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  s used internall
35340 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65  y to perform the
35350 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61  .** conversion a
35360 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e  utomatically.  ^
35370 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  (The following t
35380 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65  able details the
35390 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20   conversions.** 
353a0 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64  that are applied
353b0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
353c0 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  ote>.** <table b
353d0 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74  order="1">.** <t
353e0 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c  r><th> Internal<
353f0 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71  br>Type <th> Req
35400 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c  uested<br>Type <
35410 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a  th>  Conversion.
35420 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  **.** <tr><td>  
35430 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54  NULL    <td> INT
35440 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75  EGER   <td> Resu
35450 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c  lt is 0.** <tr><
35460 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
35470 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
35480 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a   Result is 0.0.*
35490 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
354a0 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
354b0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
354c0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
354d0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
354e0 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  LL    <td>   BLO
354f0 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  B    <td> Result
35500 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
35510 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
35520 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c  NTEGER  <td>  FL
35530 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
35540 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72  ert from integer
35550 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72   to float.** <tr
35560 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
35570 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
35580 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
35590 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65  ng of the intege
355a0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
355b0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c  TEGER  <td>   BL
355c0 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
355d0 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54  as INTEGER->TEXT
355e0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
355f0 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OAT   <td> INTEG
35600 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  ER   <td> [CAST]
35610 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c   to INTEGER.** <
35620 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
35630 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
35640 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
35650 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61  ring of the floa
35660 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  t.** <tr><td>  F
35670 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c  LOAT   <td>   BL
35680 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  OB    <td> [CAST
35690 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72  ] to BLOB.** <tr
356a0 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
356b0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
356c0 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54  d> [CAST] to INT
356d0 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  EGER.** <tr><td>
356e0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
356f0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43  FLOAT    <td> [C
35700 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20  AST] to REAL.** 
35710 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
35720 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
35730 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a   <td> No change.
35740 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
35750 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  B    <td> INTEGE
35760 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20  R   <td> [CAST] 
35770 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74  to INTEGER.** <t
35780 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
35790 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
357a0 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45  td> [CAST] to RE
357b0 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  AL.** <tr><td>  
357c0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54  BLOB    <td>   T
357d0 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20  EXT    <td> Add 
357e0 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  a zero terminato
357f0 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c  r if needed.** <
35800 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f  /table>.** </blo
35810 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
35820 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20   Note that when 
35830 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  type conversions
35840 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73   occur, pointers
35850 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69   returned by pri
35860 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  or.** calls to s
35870 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
35880 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f  ob(), sqlite3_co
35890 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64  lumn_text(), and
358a0 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  /or.** sqlite3_c
358b0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d  olumn_text16() m
358c0 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  ay be invalidate
358d0 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65  d..** Type conve
358e0 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74  rsions and point
358f0 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73  er invalidations
35900 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
35910 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  in the following
35920 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75   cases:.**.** <u
35930 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  l>.** <li> The i
35940 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
35950 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c  s a BLOB and sql
35960 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
35970 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
35980 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
35990 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
359a0 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61    A zero-termina
359b0 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20  tor might.**    
359c0 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64    need to be add
359d0 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67  ed to the string
359e0 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
359f0 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
35a00 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74  nt is UTF-8 text
35a10 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
35a20 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72  umn_bytes16() or
35a30 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
35a40 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
35a50 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
35a60 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
35a70 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
35a80 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c     to UTF-16.</l
35a90 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
35aa0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
35ab0 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e  s UTF-16 text an
35ac0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
35ad0 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20  _bytes() or.**  
35ae0 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
35af0 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c  mn_text() is cal
35b00 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
35b10 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
35b20 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
35b30 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  TF-8.</li>.** </
35b40 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65  ul>.**.** ^Conve
35b50 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55  rsions between U
35b60 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d  TF-16be and UTF-
35b70 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20  16le are always 
35b80 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e  done in place an
35b90 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61  d do.** not inva
35ba0 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70  lidate a prior p
35bb0 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f  ointer, though o
35bc0 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e  f course the con
35bd0 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66  tent of the buff
35be0 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70  er.** that the p
35bf0 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66  rior pointer ref
35c00 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76  erences will hav
35c10 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e  e been modified.
35c20 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a    Other kinds.**
35c30 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61   of conversion a
35c40 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  re done in place
35c50 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73   when it is poss
35c60 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69  ible, but someti
35c70 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20  mes they.** are 
35c80 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64  not possible and
35c90 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20   in those cases 
35ca0 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61  prior pointers a
35cb0 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  re invalidated..
35cc0 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74  **.** The safest
35cd0 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e   policy is to in
35ce0 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69  voke these routi
35cf0 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66  nes.** in one of
35d00 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77   the following w
35d10 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ays:.**.** <ul>.
35d20 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
35d30 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f  column_text() fo
35d40 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
35d50 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
35d60 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
35d70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
35d80 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  b() followed by 
35d90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
35da0 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
35db0 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
35dc0 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c  mn_text16() foll
35dd0 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
35de0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
35df0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
35e00 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  *.** In other wo
35e10 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20  rds, you should 
35e20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  call sqlite3_col
35e30 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73  umn_text(),.** s
35e40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
35e50 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  ob(), or sqlite3
35e60 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
35e70 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20   first to force 
35e80 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  the result.** in
35e90 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66  to the desired f
35ea0 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f  ormat, then invo
35eb0 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ke sqlite3_colum
35ec0 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
35ed0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
35ee0 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64  ytes16() to find
35ef0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
35f00 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74   result.  Do not
35f10 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f   mix calls.** to
35f20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
35f30 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
35f40 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
35f50 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  with calls to.**
35f60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
35f70 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64  bytes16(), and d
35f80 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20  o not mix calls 
35f90 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
35fa0 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69  n_text16().** wi
35fb0 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  th calls to sqli
35fc0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
35fd0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ()..**.** ^The p
35fe0 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
35ff0 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
36000 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
36010 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20  on occurs as.** 
36020 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c  described above,
36030 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74   or until [sqlit
36040 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
36050 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
36060 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
36070 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61  inalize()] is ca
36080 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f  lled.  ^The memo
36090 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f  ry space used to
360a0 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a   hold strings.**
360b0 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72   and BLOBs is fr
360c0 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  eed automaticall
360d0 79 2e 20 20 44 6f 20 3c 65 6d 3e 6e 6f 74 3c 2f  y.  Do <em>not</
360e0 65 6d 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69  em> pass the poi
360f0 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a  nters returned.*
36100 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
36110 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20  column_blob()], 
36120 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
36130 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e  text()], etc. in
36140 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
36150 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ree()]..**.** ^(
36160 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  If a memory allo
36170 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
36180 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65  urs during the e
36190 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79  valuation of any
361a0 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75  .** of these rou
361b0 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74  tines, a default
361c0 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e   value is return
361d0 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  ed.  The default
361e0 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74   value.** is eit
361f0 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20  her the integer 
36200 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20  0, the floating 
36210 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30  point number 0.0
36220 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  , or a NULL.** p
36230 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75  ointer.  Subsequ
36240 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
36250 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
36260 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20   will return.** 
36270 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29  [SQLITE_NOMEM].)
36280 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ^.*/.SQLITE_API 
36290 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49  const void *SQLI
362a0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
362b0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73  e3_column_blob(s
362c0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
362d0 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
362e0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
362f0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
36300 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69  olumn_bytes(sqli
36310 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
36320 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
36330 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
36340 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ALL sqlite3_colu
36350 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  mn_bytes16(sqlit
36360 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
36370 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
36380 64 6f 75 62 6c 65 20 53 51 4c 49 54 45 5f 53 54  double SQLITE_ST
36390 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f  DCALL sqlite3_co
363a0 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69  lumn_double(sqli
363b0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
363c0 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
363d0 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
363e0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ALL sqlite3_colu
363f0 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  mn_int(sqlite3_s
36400 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
36410 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
36420 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 45  te3_int64 SQLITE
36430 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
36440 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71  _column_int64(sq
36450 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
36460 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
36470 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  PI const unsigne
36480 64 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53  d char *SQLITE_S
36490 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
364a0 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74  olumn_text(sqlit
364b0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
364c0 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
364d0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49  const void *SQLI
364e0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
364f0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
36500 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
36510 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
36520 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
36530 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
36540 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c  _column_type(sql
36550 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
36560 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
36570 49 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  I sqlite3_value 
36580 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
36590 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
365a0 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
365b0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a  t*, int iCol);..
365c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
365d0 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72  Destroy A Prepar
365e0 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
365f0 65 63 74 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f  ect.** DESTRUCTO
36600 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  R: sqlite3_stmt.
36610 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
36620 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75  e3_finalize() fu
36630 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
36640 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72   to delete a [pr
36650 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
36660 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  ]..** ^If the mo
36670 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61  st recent evalua
36680 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74  tion of the stat
36690 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65  ement encountere
366a0 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f  d no errors.** o
366b0 72 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65  r if the stateme
366c0 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e  nt is never been
366d0 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e   evaluated, then
366e0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
366f0 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53  e() returns.** S
36700 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74  QLITE_OK.  ^If t
36710 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
36720 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61  valuation of sta
36730 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c  tement S failed,
36740 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
36750 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74  _finalize(S) ret
36760 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72  urns the appropr
36770 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
36780 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
36790 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a  d error code]..*
367a0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
367b0 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f  3_finalize(S) ro
367c0 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c  utine can be cal
367d0 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74  led at any point
367e0 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c   during.** the l
367f0 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72  ife cycle of [pr
36800 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
36810 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73  ] S:.** before s
36820 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76  tatement S is ev
36830 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66  er evaluated, af
36840 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f  ter.** one or mo
36850 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  re calls to [sql
36860 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f  ite3_reset()], o
36870 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c  r after any call
36880 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
36890 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65  step()] regardle
368a0 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
368b0 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65   not the stateme
368c0 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65  nt has.** comple
368d0 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a  ted execution..*
368e0 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73  *.** ^Invoking s
368f0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
36900 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) on a NULL poin
36910 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73  ter is a harmles
36920 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54  s no-op..**.** T
36930 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
36940 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65  ust finalize eve
36950 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ry [prepared sta
36960 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72  tement] in order
36970 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73   to avoid.** res
36980 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74  ource leaks.  It
36990 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 65   is a grievous e
369a0 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70  rror for the app
369b0 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20  lication to try 
369c0 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70  to use.** a prep
369d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
369e0 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
369f0 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79   finalized.  Any
36a00 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 72   use of a prepar
36a10 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
36a20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
36a30 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20  n finalized can 
36a40 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69  result in undefi
36a50 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73  ned and.** undes
36a60 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20  irable behavior 
36a70 73 75 63 68 20 61 73 20 73 65 67 66 61 75 6c 74  such as segfault
36a80 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75  s and heap corru
36a90 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ption..*/.SQLITE
36aa0 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
36ab0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
36ac0 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33  finalize(sqlite3
36ad0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
36ae0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
36af0 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64  Reset A Prepared
36b00 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
36b10 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
36b20 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
36b30 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65  The sqlite3_rese
36b40 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  t() function is 
36b50 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20  called to reset 
36b60 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
36b70 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74  ement].** object
36b80 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
36b90 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64  tial state, read
36ba0 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75  y to be re-execu
36bb0 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c  ted..** ^Any SQL
36bc0 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61   statement varia
36bd0 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61  bles that had va
36be0 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68  lues bound to th
36bf0 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20  em using.** the 
36c00 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
36c10 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  ob | sqlite3_bin
36c20 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69  d_*() API] retai
36c30 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a  n their values..
36c40 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f  ** Use [sqlite3_
36c50 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29  clear_bindings()
36c60 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62  ] to reset the b
36c70 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e  indings..**.** ^
36c80 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
36c90 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
36ca0 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65   resets the [pre
36cb0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
36cc0 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68   S.** back to th
36cd0 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69  e beginning of i
36ce0 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a  ts program..**.*
36cf0 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
36d00 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
36d10 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
36d20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  for the.** [prep
36d30 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
36d40 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  S returned [SQLI
36d50 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49  TE_ROW] or [SQLI
36d60 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20  TE_DONE],.** or 
36d70 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  if [sqlite3_step
36d80 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62  (S)] has never b
36d90 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65  efore been calle
36da0 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20  d on S,.** then 
36db0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
36dc0 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  )] returns [SQLI
36dd0 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  TE_OK]..**.** ^I
36de0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
36df0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
36e00 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
36e10 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
36e20 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
36e30 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72  dicated an error
36e40 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74  , then.** [sqlit
36e50 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74  e3_reset(S)] ret
36e60 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69  urns an appropri
36e70 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
36e80 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
36e90 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
36ea0 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e  interface does n
36eb0 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
36ec0 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b  lues.** of any [
36ed0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
36ee0 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74  b|bindings] on t
36ef0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
36f00 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 51  tement] S..*/.SQ
36f10 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
36f20 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
36f30 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65  te3_reset(sqlite
36f40 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
36f50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36f60 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66   Create Or Redef
36f70 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ine SQL Function
36f80 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
36f90 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f  function creatio
36fa0 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b  n routines}.** K
36fb0 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63  EYWORDS: {applic
36fc0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
36fd0 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b  L function}.** K
36fe0 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63  EYWORDS: {applic
36ff0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
37000 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20  L functions}.** 
37010 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
37020 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  **.** ^These fun
37030 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69  ctions (collecti
37040 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66  vely known as "f
37050 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
37060 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61   routines").** a
37070 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53  re used to add S
37080 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
37090 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f  aggregates or to
370a0 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65   redefine the be
370b0 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69  havior.** of exi
370c0 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69  sting SQL functi
370d0 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
370e0 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66  s.  The only dif
370f0 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e  ferences between
37100 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e  .** these routin
37110 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20  es are the text 
37120 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65  encoding expecte
37130 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63  d for.** the sec
37140 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74  ond parameter (t
37150 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66  he name of the f
37160 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72  unction being cr
37170 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68  eated).** and th
37180 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62  e presence or ab
37190 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72  sence of a destr
371a0 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66  uctor callback f
371b0 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  or.** the applic
371c0 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
371d0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  er..**.** ^The f
371e0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
371f0 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
37200 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77  connection] to w
37210 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20  hich the SQL.** 
37220 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62  function is to b
37230 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e  e added.  ^If an
37240 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65   application use
37250 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  s more than one 
37260 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
37270 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c  ection then appl
37280 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
37290 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75  SQL functions mu
372a0 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74  st be added.** t
372b0 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
372c0 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72  connection separ
372d0 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ately..**.** ^Th
372e0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
372f0 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
37300 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
37310 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64  on to be created
37320 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64   or.** redefined
37330 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f  .  ^The length o
37340 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69  f the name is li
37350 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74  mited to 255 byt
37360 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a  es in a UTF-8.**
37370 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c   representation,
37380 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68   exclusive of th
37390 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  e zero-terminato
373a0 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  r.  ^Note that t
373b0 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74  he name.** lengt
373c0 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54  h limit is in UT
373d0 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63  F-8 bytes, not c
373e0 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54  haracters nor UT
373f0 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a  F-16 bytes.  .**
37400 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f   ^Any attempt to
37410 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69   create a functi
37420 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72  on with a longer
37430 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65   name.** will re
37440 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f  sult in [SQLITE_
37450 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65  MISUSE] being re
37460 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
37470 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
37480 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20  er (nArg).** is 
37490 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  the number of ar
374a0 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65  guments that the
374b0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
374c0 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61  .** aggregate ta
374d0 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61  kes. ^If this pa
374e0 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74  rameter is -1, t
374f0 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hen the SQL func
37500 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
37510 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e  gate may take an
37520 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  y number of argu
37530 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20  ments between 0 
37540 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a  and the limit.**
37550 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33   set by [sqlite3
37560 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f  _limit]([SQLITE_
37570 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
37580 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68  RG]).  If the th
37590 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
375a0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31   is less than -1
375b0 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
375c0 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65   127 then the be
375d0 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64  havior is.** und
375e0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
375f0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
37600 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73  ter, eTextRep, s
37610 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a  pecifies what.**
37620 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20   [SQLITE_UTF8 | 
37630 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74  text encoding] t
37640 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  his SQL function
37650 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20   prefers for.** 
37660 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20  its parameters. 
37670 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
37680 20 73 68 6f 75 6c 64 20 73 65 74 20 74 68 69 73   should set this
37690 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
376a0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
376b0 5d 20 69 66 20 74 68 65 20 66 75 6e 63 74 69 6f  ] if the functio
376c0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
376d0 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71   invokes .** [sq
376e0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
376f0 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e  16le()] on an in
37700 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  put, or [SQLITE_
37710 55 54 46 31 36 42 45 5d 20 69 66 20 74 68 65 0a  UTF16BE] if the.
37720 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
37730 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74  n invokes [sqlit
37740 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
37750 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74  e()] on an input
37760 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  , or.** [SQLITE_
37770 55 54 46 31 36 5d 20 69 66 20 5b 73 71 6c 69 74  UTF16] if [sqlit
37780 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
37790 29 5d 20 69 73 20 75 73 65 64 2c 20 6f 72 20 5b  )] is used, or [
377a0 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a 2a 2a 20  SQLITE_UTF8].** 
377b0 6f 74 68 65 72 77 69 73 65 2e 20 20 5e 54 68 65  otherwise.  ^The
377c0 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69   same SQL functi
377d0 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74  on may be regist
377e0 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69  ered multiple ti
377f0 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20 64 69 66  mes using.** dif
37800 66 65 72 65 6e 74 20 70 72 65 66 65 72 72 65 64  ferent preferred
37810 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2c   text encodings,
37820 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20   with different 
37830 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
37840 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65 6e 63 6f  for.** each enco
37850 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d  ding..** ^When m
37860 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
37870 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
37880 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65  ame function are
37890 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69   available, SQLi
378a0 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20  te.** will pick 
378b0 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76  the one that inv
378c0 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20  olves the least 
378d0 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63  amount of data c
378e0 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  onversion..**.**
378f0 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
37900 61 6d 65 74 65 72 20 6d 61 79 20 6f 70 74 69 6f  ameter may optio
37910 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64 20 77 69  nally be ORed wi
37920 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52  th [SQLITE_DETER
37930 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 74 6f 20  MINISTIC].** to 
37940 73 69 67 6e 61 6c 20 74 68 61 74 20 74 68 65 20  signal that the 
37950 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c  function will al
37960 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20  ways return the 
37970 73 61 6d 65 20 72 65 73 75 6c 74 20 67 69 76 65  same result give
37980 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 69 6e  n.** the same in
37990 70 75 74 73 20 77 69 74 68 69 6e 20 61 20 73 69  puts within a si
379a0 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65  ngle SQL stateme
379b0 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c 20 66 75  nt.  Most SQL fu
379c0 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a 2a 20 64  nctions are.** d
379d0 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54  eterministic.  T
379e0 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b 72 61 6e  he built-in [ran
379f0 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75 6e 63 74  dom()] SQL funct
37a00 69 6f 6e 20 69 73 20 61 6e 20 65 78 61 6d 70 6c  ion is an exampl
37a10 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e 63 74 69  e of a.** functi
37a20 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20 64  on that is not d
37a30 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54  eterministic.  T
37a40 68 65 20 53 51 4c 69 74 65 20 71 75 65 72 79 20  he SQLite query 
37a50 70 6c 61 6e 6e 65 72 20 69 73 20 61 62 6c 65 20  planner is able 
37a60 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d 20 61 64  to.** perform ad
37a70 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a  ditional optimiz
37a80 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74 65 72 6d  ations on determ
37a90 69 6e 69 73 74 69 63 20 66 75 6e 63 74 69 6f 6e  inistic function
37aa0 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 6f 66 20  s, so use.** of 
37ab0 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 54 45  the [SQLITE_DETE
37ac0 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c 61 67 20  RMINISTIC] flag 
37ad0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 77  is recommended w
37ae0 68 65 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a  here possible..*
37af0 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68  *.** ^(The fifth
37b00 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e   parameter is an
37b10 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74   arbitrary point
37b20 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65  er.  The impleme
37b30 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a  ntation of the.*
37b40 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67  * function can g
37b50 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68  ain access to th
37b60 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67  is pointer using
37b70 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
37b80 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ata()].)^.**.** 
37b90 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65  ^The sixth, seve
37ba0 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70  nth and eighth p
37bb0 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63  arameters, xFunc
37bc0 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  , xStep and xFin
37bd0 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74  al, are.** point
37be0 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67  ers to C-languag
37bf0 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  e functions that
37c00 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
37c10 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
37c20 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20  * aggregate. ^A 
37c30 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
37c40 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
37c50 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
37c60 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63  f the xFunc.** c
37c70 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55  allback only; NU
37c80 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74  LL pointers must
37c90 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
37ca0 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  e xStep and xFin
37cb0 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  al.** parameters
37cc0 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20  . ^An aggregate 
37cd0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
37ce0 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
37cf0 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70  ntation of xStep
37d00 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61  .** and xFinal a
37d10 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  nd NULL pointer 
37d20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66  must be passed f
37d30 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65  or xFunc. ^To de
37d40 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67  lete an existing
37d50 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
37d60 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70   or aggregate, p
37d70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ass NULL pointer
37d80 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20  s for all three 
37d90 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  function.** call
37da0 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  backs..**.** ^(I
37db0 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61  f the ninth para
37dc0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
37dd0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
37de0 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c  _v2() is not NUL
37df0 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  L,.** then it is
37e00 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20   destructor for 
37e10 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
37e20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a  data pointer. .*
37e30 2a 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72  * The destructor
37e40 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
37e50 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
37e60 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72   deleted, either
37e70 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65   by being.** ove
37e80 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20  rloaded or when 
37e90 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
37ea0 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29  nection closes.)
37eb0 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75  ^.** ^The destru
37ec0 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76  ctor is also inv
37ed0 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c  oked if the call
37ee0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
37ef0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
37f00 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57  2() fails..** ^W
37f10 68 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74  hen the destruct
37f20 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74  or callback of t
37f30 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74  he tenth paramet
37f40 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69  er is invoked, i
37f50 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61  t.** is passed a
37f60 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
37f70 20 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79   which is a copy
37f80 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
37f90 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69  ion data .** poi
37fa0 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74  nter which was t
37fb0 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
37fc0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  er to sqlite3_cr
37fd0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
37fe0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73  ()..**.** ^It is
37ff0 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65   permitted to re
38000 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20  gister multiple 
38010 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
38020 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66  of the same.** f
38030 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68  unctions with th
38040 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20  e same name but 
38050 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66  with either diff
38060 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66  ering numbers of
38070 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  .** arguments or
38080 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65   differing prefe
38090 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
380a0 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69  ngs.  ^SQLite wi
380b0 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d  ll use.** the im
380c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61  plementation tha
380d0 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d  t most closely m
380e0 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69  atches the way i
380f0 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53  n which the.** S
38100 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  QL function is u
38110 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f  sed.  ^A functio
38120 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
38130 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61   with a non-nega
38140 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72  tive.** nArg par
38150 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74  ameter is a bett
38160 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
38170 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
38180 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20  ntation with.** 
38190 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e  a negative nArg.
381a0 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68    ^A function wh
381b0 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  ere the preferre
381c0 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a  d text encoding.
381d0 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64  ** matches the d
381e0 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67  atabase encoding
381f0 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20   is a better.** 
38200 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
38210 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
38220 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66  encoding is diff
38230 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66  erent.  .** ^A f
38240 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
38250 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65  e encoding diffe
38260 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e  rence is between
38270 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46   UTF16le and UTF
38280 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f  16be.** is a clo
38290 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61  ser match than a
382a0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
382b0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66  the encoding dif
382c0 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65  ference is.** be
382d0 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55  tween UTF8 and U
382e0 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69  TF16..**.** ^Bui
382f0 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20  lt-in functions 
38300 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65  may be overloade
38310 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61  d by new applica
38320 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
38330 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  ctions..**.** ^A
38340 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
38350 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  fined function i
38360 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63  s permitted to c
38370 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c  all other.** SQL
38380 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20  ite interfaces. 
38390 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63   However, such c
383a0 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a  alls must not.**
383b0 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62   close the datab
383c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e  ase connection n
383d0 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72  or finalize or r
383e0 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
383f0 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69  d.** statement i
38400 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63  n which the func
38410 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
38420 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
38430 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
38440 4c 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  L sqlite3_create
38450 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c  _function(.  sql
38460 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
38470 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f  t char *zFunctio
38480 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
38490 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
384a0 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
384b0 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
384c0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
384d0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
384e0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
384f0 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
38500 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
38510 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
38520 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
38530 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
38540 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ).);.SQLITE_API 
38550 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
38560 4c 4c 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  LL sqlite3_creat
38570 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20  e_function16(.  
38580 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
38590 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63  onst void *zFunc
385a0 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
385b0 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
385c0 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
385d0 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
385e0 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
385f0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
38600 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
38610 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
38620 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
38630 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
38640 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
38650 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
38660 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  xt*).);.SQLITE_A
38670 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
38680 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 72  DCALL sqlite3_cr
38690 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
386a0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
386b0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
386c0 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
386d0 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
386e0 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
386f0 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
38700 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
38710 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
38720 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
38730 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
38740 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*